{"openapi":"3.1.0","info":{"title":"x-unlock User API","version":"1.0.0","description":"API for X (Twitter) account checking and unlocking. Submit accounts as an order, poll its status, then download the results. Orders are paid from your prepaid wallet balance. Create an API key in the dashboard (API keys). Send `Authorization: Bearer xul_...` on every request. USD amounts are 4-decimal strings; your key only ever spends your own wallet and reads your own orders. Rate limits are per API key: 10 create-order req/min, 30/min for cancel, results and accounts. Responses carry `X-RateLimit-*` and `Retry-After` headers; a 429 means slow down."},"servers":[{"url":"https://x-unlock.shop/api/v1","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"xul_ API key"}},"schemas":{"Target":{"type":"object","additionalProperties":false,"description":"An account to process. Provide EITHER username + password (+ twoFactor), OR authToken on its own (if authToken is present it is used and username/password are ignored).","anyOf":[{"required":["username","password"]},{"required":["authToken"]}],"properties":{"username":{"type":"string","maxLength":4096},"password":{"type":"string","maxLength":4096},"twoFactor":{"type":"string","maxLength":4096,"description":"TOTP secret key (not a code). Omit if none."},"authToken":{"type":"string","pattern":"^[a-fA-F0-9]{40}$","description":"auth_token-only mode: a 40-char hex X auth_token, used ALONE (no username/password)."}}},"CreateOrder":{"type":"object","required":["targets"],"additionalProperties":false,"properties":{"targets":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Target"}},"unlockEnabled":{"type":"boolean","default":true,"description":"false = check only (no unlock)."},"proxyCountry":{"type":"string","default":"US","description":"Uppercase country code from the supported proxy list (GET /pricing → proxyCountries)."},"idempotencyKey":{"type":"string","maxLength":128,"description":"Alternative to the Idempotency-Key header; a retry with the same value returns the first order."}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["creating","queued","waiting","in_progress","completed","timed_out","cancelled","failed"]},"unlockEnabled":{"type":"boolean"},"proxyCountry":{"type":"string"},"targetCount":{"type":"integer"},"unlockedCount":{"type":"integer"},"alreadyUnlockedCount":{"type":"integer"},"lockedCount":{"type":"integer"},"checkFailedCount":{"type":"integer"},"freeCount":{"type":"integer"},"precharged":{"type":"string","description":"Max charge held from your wallet (USD, 4dp)."},"charged":{"type":"string","description":"Final charge (USD, 4dp)."},"refunded":{"type":"string","description":"Refunded to your wallet on close (USD, 4dp)."},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"reportExpiresAt":{"type":"string","format":"date-time","nullable":true}}},"Account":{"type":"object","description":"One account's result. No credentials/tokens — `web`/`android` are availability booleans; `charge` is YOUR price for that account (never our cost).","properties":{"line":{"type":"integer"},"username":{"type":"string"},"outcome":{"type":"string","enum":["unlocked","already_unlocked","locked","check_failed","free"]},"reason":{"type":"string"},"web":{"type":"boolean","description":"Web login tokens (authToken+ct0) present."},"android":{"type":"boolean","description":"Android login tokens (oauthToken+oauthSecret) present."},"charge":{"type":"string","description":"Your charge for this account (USD, 4dp)."}}},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}},"paths":{"/me":{"get":{"summary":"Get your profile and wallet balance","responses":{"200":{"description":"Your profile + balance.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"email":{"type":"string"},"balance":{"type":"string"},"suspended":{"type":"boolean"}}}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/pricing":{"get":{"summary":"Get current prices, limits, and supported proxy regions","responses":{"200":{"description":"Current prices (already marked up; the markup itself is never exposed).","content":{"application/json":{"schema":{"type":"object","properties":{"pricing":{"type":"object","properties":{"successRate":{"type":"string"},"checkFee":{"type":"string"},"maxTargets":{"type":"integer"},"minTopUp":{"type":"string"},"maxTopUp":{"type":"string"},"ordersAvailable":{"type":"boolean"}}},"proxyCountries":{"type":"array","items":{"type":"string"},"description":"Uppercase country codes accepted as `proxyCountry` on an order."}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/pricing/quote":{"get":{"summary":"Estimate the cost of N unlocks at your pricing and volume","parameters":[{"name":"n","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":100000}}],"responses":{"200":{"description":"Cost estimate for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"object","properties":{"accounts":{"type":"integer"},"yourVolume":{"type":"integer"},"unlockCost":{"type":"string"},"avgPerUnlock":{"type":"string"},"checkOnlyCost":{"type":"string"}}}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders":{"post":{"summary":"Create an order (charges your wallet)","description":"Validates the accounts, holds the maximum charge from your wallet and submits them. Send an `Idempotency-Key` header (or `idempotencyKey` in the body) so a retry never creates a second order.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"201":{"description":"Order accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"summary":"List your orders (newest first, 10 per page)","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Your orders.","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}":{"get":{"summary":"Get one order's status and progress","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order status.","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}/results":{"get":{"summary":"Download results of a finished order","description":"Returns results after the order is completed or timed_out. `format` = json (default) | csv | txt. `content` = full | usernames | custom (+ `columns`). `outcome`, `credentialFilter`, `delimiter`, `includeHeader` as documented. Include `password` and/or `twoFactor` in `columns` to get the FULL login format: the credentials you submitted, merged with the returned login tokens and rendered in your chosen format. Those two are available only while the report is (within 24h of completion); after that they come back blank.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv","txt"]}},{"name":"content","in":"query","schema":{"type":"string","enum":["full","usernames","custom"]}},{"name":"columns","in":"query","schema":{"type":"array","items":{"type":"string","enum":["lineNumber","username","password","twoFactor","authToken","ct0","oauthToken","oauthSecret","outcome","reason"]}}},{"name":"outcome","in":"query","description":"Filter to one result type (raw keys; the dashboard shows `free` as \"No Change\").","schema":{"type":"string","enum":["unlocked","already_unlocked","locked","check_failed","free"]}},{"name":"credentialFilter","in":"query","schema":{"type":"string","enum":["none","web","android","any"]}},{"name":"delimiter","in":"query","schema":{"type":"string","enum":["tab","colon","semicolon","pipe"]}},{"name":"includeHeader","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Results (json/csv/txt)."},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}/accounts":{"get":{"summary":"Per-account results (structured JSON; no credentials/tokens)","description":"Outcome, reason, web/android availability and YOUR charge for each account. Up to 1000 rows; `total` is the full count.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Per-account results.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"total":{"type":"integer"}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel an unstarted order (full refund to wallet)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Invalid API key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden (e.g. account suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Order not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict (e.g. insufficient balance, order not finished).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Report expired (results no longer available).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Order too large (too many accounts or over the per-order max).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Upstream temporarily unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}