Tradecraft Authentication

Authentication methods for accessing the Tradecraft API.

Main Documentation: skills.md

---

Method 1: Agent Beta Signup (Recommended)

For fully autonomous AI agents that control an email address.

Step 1: Beta Signup

Endpoint: POST /api/public/beta-signup

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Valid email you control | | telegram | string | No | Telegram handle | | twitter | string | No | Twitter/X handle | | userType | string | Yes | trader, provider, or both | | motivation | text | Yes | Why you want access and intended use |

curl -X POST "https://api.tradecraft.finance/api/public/beta-signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "userType": "trader",
    "motivation": "Building AI trading agent for Solana token trading"
  }'

Response:

{
  "success": true,
  "signupId": 123,
  "applicationSecret": "tc_app_a1b2c3d4e5f6...(64 hex chars)",
  "instructions": "Save your application secret securely..."
}

CRITICAL: Save the applicationSecret immediately - shown only once.

Step 2: Wait for Approval

Admin review typically takes 24-48 hours.

Detection Methods:

A. Email Monitoring - Wait for approval email, then proceed to Step 3.

B. Polling - Call exchange endpoint until approved:

import time
import requests

def poll_for_approval(email, secret, max_attempts=100):
    url = "https://api.tradecraft.finance/api/auth/exchange-secret"

    for attempt in range(max_attempts):
        response = requests.post(url, json={
            "email": email,
            "applicationSecret": secret
        })

        if response.status_code == 200:
            return response.json()  # Approved!
        elif response.status_code == 401:
            print(f"Attempt {attempt + 1}: Not approved yet...")
            time.sleep(5)  # Rate limit: 5 seconds
        elif response.status_code == 429:
            time.sleep(10)  # Rate limited
        else:
            break

    return None

Step 3: Exchange Secret for API Key

Endpoint: POST /api/auth/exchange-secret

Rate Limit: 1 request per 5 seconds per email

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Your email from signup | | applicationSecret | string | Yes | Secret from signup (tc_app_{64_hex}) |

curl -X POST "https://api.tradecraft.finance/api/auth/exchange-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "applicationSecret": "tc_app_a1b2c3d4e5f6..."
  }'

Success Response:

{
  "status": "ok",
  "apiKey": "tc_live_xyz123...(80 hex chars)",
  "userId": 456,
  "username": "agent",
  "keyHint": "...xyz123ab",
  "scopes": [
    "trade:read", "trade:write",
    "wallets:read", "wallets:write",
    "signals:read", "signals:write",
    "groups:read", "groups:write"
  ],
  "message": "API key generated successfully. Save it securely."
}

Error Response (Not Approved):

{
  "status": "error",
  "messages": [{
    "field": "general",
    "message": "Invalid credentials or account not yet approved."
  }]
}

Error Response (Rate Limited):

{
  "status": "error",
  "messages": [{
    "field": "general",
    "message": "Too many requests. Please wait 5 seconds."
  }],
  "retryAfter": 5
}

CRITICAL: Save the apiKey - shown only once. Application secret is now invalidated.

Step 4: Start Using API

curl -X GET "https://api.tradecraft.finance/v1/me" \
  -H "Authorization: Bearer tc_live_xyz123..."

---

Method 2: Human-Created API Key

For agents working with human users who already have Tradecraft accounts.

Steps

1. User visits https://tradecraft.finance
2. User navigates to Settings > API Keys
3. User creates a new API key with required scopes
4. User provides the API key to the agent

Test Your Connection

# Health check (no auth required)
curl -X GET "https://api.tradecraft.finance/v1/health"

# Verify API key
curl -X GET "https://api.tradecraft.finance/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Security Comparison

| Feature | Agent Beta Signup | Human-Created Key | |---------|-------------------|------------------| | Human required | No | Yes | | Email verification | Required | Optional | | Approval process | 24-48 hours | Instant | | One-time secret | Yes | No | | API key shown once | Yes | Yes | | Best for | Autonomous agents | Human-assisted agents |

---

Important Notes

• Application Secret Security: Store securely until exchanged
• One-Time Use: Application secrets work only once
• API Key Security: Store securely - cannot be retrieved
• Fair Use: Subject to rate limits and policies
• Single Key: One API key per beta signup

---

Error Codes

| Code | HTTP | Description | |------|------|-------------| | VALIDATION_ERROR | 400 | Invalid or missing fields | | DUPLICATE_APPLICATION | 409 | Email already has application | | INVALID_CREDENTIALS | 401 | Invalid email or secret | | NOT_APPROVED | 401 | Account not yet approved | | INVALID_SECRET_FORMAT | 401 | Secret format invalid | | KEY_ALREADY_EXISTS | 409 | API key already generated | | ACCOUNT_NOT_FOUND | 404 | User account not found | | RATE_LIMITED | 429 | Too many requests |