CodeSolvers

Token API Quick Guide

---

### General Rules

- The UserAgent field must begin with a string from the *AllowedUserAgents* list configured on the server.
- If a *SiteKeyUserAgents* list exists for a given SiteKey, the supplied UserAgent must match one of those entries exactly.

---

## 1. POST /api/token/createTask
Starts a token‑generation task.

### Request Body

{
  "ApiKey":   "string",      // required
  "Blob":     "string",      // URL‑encoded challenge blob
  "UserAgent":"string",      // must satisfy the rules above
  "Proxy": {                 // optional
    "Address": "host:port",
    "Username": "proxyUser",
    "Password": "proxyPass"
  },
  "SiteKey":  "string",      // one of SupportedSiteKeys
  "SiteUrl":  "https://example.com"
}

### Example cURL

curl -X POST http://37.27.240.144:5000/api/token/createTask       -H "Content-Type: application/json"       -d '{
        "ApiKey":   "YOUR_API_KEY",
        "Blob":     "BASE64_OR_URL_ENCODED_BLOB",
        "UserAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
        "SiteKey":  "2CB16598-CB82-4CF7-B332-5990DB66F3AB",
        "SiteUrl":  "https://example.com"
      }'

### Possible Error Responses
| Code | Meaning |
|------|---------|
| ERROR_API_KEY | API key missing or invalid |
| ERROR_MISSING_BLOB • ERROR_MISSING_USER_AGENT • ERROR_MISSING_SITE_KEY • ERROR_MISSING_SITE_URL | Required field is missing |
| UNSUPPORTED_USER_AGENT | UA not in AllowedUserAgents |
| UNSUPPORTED_SITE_KEY | Unsupported SiteKey |
| SITEKEY_USER_AGENT_MISMATCH | UA does not match the list for that SiteKey |
| ERROR_NO_BALANCE | No remaining credit |
| ERROR_RATE_LIMIT | Too many createTask requests |

---

## 2. GET /api/token/getTask/{sessionId}
Checks the status of an existing task.

### Parameters
- sessionId – ID returned from createTask
- apiKey (query) – the same API key used to create the task

### Example cURL

curl "http://37.27.240.144:5000/api/token/getTask/<SESSION_ID>?apiKey=YOUR_API_KEY"

### Responses
- Still processing

  { "success": false, "taskType": "PROCESSING" }

- On success

  { "success": true, "taskType": "SUCCESS", "token": "<token>" }

- On failure

  { "success": false, "taskType": "FAILED", "message": "<error>" }

> ERROR_INVALID_TASK_DATA or ERROR_API_KEY_MISMATCH are returned if the session ID is unknown or the API key does not match.

---

## 3. GET /api/token/getBalance
Returns the remaining credit for the specified API key.

### Query Parameter
- apiKey – the user's API key

### Example cURL

curl "http://37.27.240.144:5000/api/token/getBalance?apiKey=YOUR_API_KEY"

### Notes (applies only to getBalance)
- If the X‑Forwarded‑For header is present, the request is rejected with ERROR_FORBIDDEN_HEADER.
- Requests from the same IP are limited to one per second (ERROR_RATE_LIMIT).

---

## Common Error Codes
| Code | Meaning |
|------|---------|
| ERROR_API_KEY | Invalid or missing API key |
| ERROR_NO_BALANCE | Insufficient credit |
| ERROR_RATE_LIMIT | Rate limit exceeded |
| UNSUPPORTED_USER_AGENT | UA not whitelisted |
| UNSUPPORTED_SITE_KEY | SiteKey not supported |
| SITEKEY_USER_AGENT_MISMATCH | UA does not match SiteKey list |
| ERROR_INVALID_TASK_DATA | Unknown session ID |
| ERROR_API_KEY_MISMATCH | Session does not belong to provided key |
| FAILED | Solver reported failure (see message) |

437 views03:03