Overview#

The Catapult API powers a synthetic-token derivatives platform — trading and token data — through a single GraphQL endpoint for request/response operations, and a WebSocket endpoint for real-time subscriptions.

Base endpoints#

All HTTP requests use POST with a JSON body of the shape { "query": "...", "variables": { ... } }.

Authentication#

Authenticated operations use a JWT bearer token, sent in the Authorization header:

Authorization: Bearer <your-jwt-token>

The token is a JSON Web Token (JWT), valid for 730 days (≈2 years) from issue by default — rotate it before it expires. Only ping is public; every other operation requires the bearer token, and reads such as tokens and turboToken also need the tokens.read permission.

Create an API key#

Generate your token from your account dashboard at catapult.trade/settings/api-key (Settings → API Key). You can manage your account at catapult.trade.

Conventions#

• IDs are opaque strings; do not parse them.
• Monetary amounts are string-encoded integers typed String! (e.g. balanceUsdtDrops) — parse them as BigInt, never as floats. The only custom scalar is DateTime.
• Timestamps use the DateTime scalar (ISO-8601, UTC).
• List queries are cursor-paginated via input.pagination: limit (default 10) with afterCursor / beforeCursor.

Quick example#

query Tokens {
  # see the Reference tab for the full PublicTokenListInput and token fields
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

API Key oAuth#

This link lets you obtain a user's API key to build features such as copy trading. The user grants the permissions on their API key, and it is passed to your whitelisted callback URL.

https://catapult.trade/settings/api-key?bot_id=<WHITELISTED_BOT_ID>

Replace <WHITELISTED_BOT_ID> with your bot's whitelisted ID.

Whitelisting of the bot#

Whitelist your bot by contacting our developer team:

[email protected]

Units & conventions#

Read this first — every monetary field on the API depends on these conventions.

USDT drops (*UsdtDrops)#

All USDT amounts are integers of USDT × 1,000,000 (6 decimals), named with a UsdtDrops suffix. They are sent as String! (string-encoded integers) — parse them as BigInt, never as floats.

Convert with usdt = drops / 1e6 and drops = round(usdt × 1e6) — compute in BigInt.

Leverage (leverageX10)#

Leverage is encoded as leverage × 10. leverageX10: 125 means 12.5×; 30 means 3×.

Collateral vs notional#

notional = collateral × leverage. The amount you put up is collateral; the position's USDT face value is notional.

When opening a position the amount is collateral, pre-fee. tradeOpen takes exactly one of usdtDrops (USDT-denominated) or amountWei (token-denominated) — the engine derives the notional from it and the leverage. It is not the notional.

Balances#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

Token media (fileId)#

A token image is attached by passing a fileId to tokenCreate. There are two ways to get one:

1. Randomizer — tokenRandomizedPreset returns a ready-to-use fileId (plus a name, symbol, mode, etc.) that you can pass straight to tokenCreate.
2. Custom upload — a three-step S3 presigned-POST flow:
   • fileUpload(input) → returns an S3 presigned-POST URL plus the form fields the client must include in the multipart POST.
   • The client POSTs the image to that S3 URL with those exact form fields.
   • fileFinalize(id) → marks the upload finished after the S3 POST succeeds and returns the public file URL; use the resulting file as the token's image.

Upload limits: JPEG or PNG only, 5 MB max, minimum 314×314 px. The presigned POST must complete within 15 seconds of the fileUpload call, and uploads are rate-limited to 200 per hour per IP.

Token speed modes#

Every token runs in one of five speed modes. The create/randomize field is turboTokenMode; token records expose speedMode. SLOW and NORMAL are the same mode under two names.

Max-leverage and lifetime values below are current configuration that can change server-side — treat them as current values and verify against the live leverage-config query.

Max leverage is a fixed engine cap#

Each mode's max leverage is a hard cap enforced by the engine — use the value in the table directly. The engine rejects any order above it.

Fees & position sizing#

Open fee (~1%)#

Opening a position charges an open fee of ~1% (0.01), deducted from the collateral you send:

collateral_post_fee = collateral_sent × (1 − fee)

To make the locked collateral land exactly at notional / leverage, send:

collateral_sent = (notional / leverage) / (1 − fee)

Per-position notional cap#

A per-position notional cap is enforced server-side — currently 20,000 USDT per (token, leverage, side). Exceeding it returns Maximum notional limit … exceeded. Verify the exact value against the live config; it may vary by mode or leverage.

Max available position (notional)#

Let fee = 0.01, free = balanceUsdtDrops / 1e6, inPos = inPositionsBalanceUsdtDrops / 1e6, capTotal = your own optional total-collateral cap, capPos = per-position notional cap (~20,000), L = leverage:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # if you enforce a total cap
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

Collateral to actually send = (maxPositionNotional / L) / (1 − fee).

Rounding pitfall. After the /(1 − fee) division, a naive round(collateral × 1e6) overshoots the cap by a few drops and the open is rejected. Floor the collateral in drops (BigInt) to a small step (e.g. 10 drops = 0.00001 USDT) before sending. You lose a negligible fraction of a cent and stay under the cap at any leverage.

Worked example#

FLASH, 3×, fee 1%, cap 20,000 notional:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (floored in drops)
→ locked post-fee ≈ 6,666.67, notional ≈ 20,000

Status Codes#

GraphQL responses return HTTP 200 even when an operation fails — inspect the errors[] array and each error's extensions.code. Transport-level problems use standard HTTP status codes.

HTTP status codes#

The GraphQL service returns auth, permission and rate-limit failures in-band as 200 responses (see GraphQL error codes). Transport-level 401 / 403 / 429 only occur if an upstream gateway/CDN rejects the request before it reaches the API.

GraphQL error codes#

Codes are case-sensitive; match the exact string. Domain codes are PascalCase (e.g. RateLimited); some framework codes are upper snake-case (e.g. UNAUTHENTICATED).

Error shape#

{
  "errors": [
    { "message": "Token not found", "extensions": { "code": "NotFound" } }
  ],
  "data": null
}

Rate Limits#

GraphQL operations share a single rate-limit bucket, keyed per API token (jti) and IP: 600 queries/min and 60 mutations/min. Exceeding a limit returns an HTTP 200 response whose errors[] contains a single error with extensions.code = RateLimited. The API does not send a 429 status or a Retry-After header; retry-timing hints are included in the error's extensions.

HTTP (GraphQL) limits#

WebSocket limits#

WebSocket limits are server-configurable, so production may differ from these defaults. Connection limits are enforced per connection, not per IP.

Response headers#

The API does not emit rate-limit headers (X-RateLimit-*, Retry-After). An upstream gateway may add them; do not depend on them.

Gotchas & idempotency#

A checklist of the things integrators get wrong most.

Money & sizing#

• Drops are integers — BigInt end to end; never float-parse *UsdtDrops.
• The open amount you send (usdtDrops or amountWei) is collateral, pre-fee — not notional.
• The notional cap is enforced in drops; floor your collateral to avoid a few-drop overshoot (see Fees & position sizing).
• Max leverage is a fixed per-mode engine cap (see Token speed modes) — use it directly.

Tokens#

• The randomizer returns a random rank (Competition | Private | Public). Force Public if the token must be listed / copy-tradeable.
• tokenCreate always uses balance-based payment — the payment type cannot be overridden.
• There is no server-side "active" flag on tokens — filter client-side on endDate.

Opening & closing#

• tradeOpen requires exactly one of usdtDrops (USDT-denominated) or amountWei (token-denominated) — never both, never neither.
• tradeClose closes an open position via USER_SELL.

Take-profit / stop-loss (tradeLimit*)#

• tradeLimitCreate requires at least one trigger (SL or TP).
• On update, an explicit null for a side clears it; an omitted field is preserved.
• tradeLimitUpdate rejects an all-null input (Validation failed: input=MissingValue) — use tradeLimitDelete to clear.
• There is no per-side delete; tradeLimitDelete removes both TP and SL.

Subscriptions (WebSocket)#

• Authenticate on connection_init with payload: { Authorization: "Bearer <apiKey>" }.
• The positions subscription streams the PublicPositionEvent union — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent. Match on the type field before reading event-specific fields.
• PublicPositionClosedEvent carries positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops. The buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10 fields belong to PublicPositionOpenedEvent, not the closed one.
• Close events are at-least-once and are not replayed. A close emitted while you reconnect is missed by the fresh subscription — poll each open position on (re)subscribe to catch missed closes, and dedupe by positionId.

WebSocket API#

Real-time data is delivered over a WebSocket connection using the GraphQL over WebSocket protocol (graphql-transport-ws). Use it for subscription operations such as live price updates.

Connection#

Open a WebSocket to:

wss://public-api.catapult.trade/graphql

Negotiate the graphql-transport-ws subprotocol. After the socket opens, send a connection_init message; the server replies with connection_ack.

Lifecycle#

1. Client opens the socket with subprotocol graphql-transport-ws.
2. Client → {"type":"connection_init"}.
3. Server → {"type":"connection_ack"}.
4. Client → subscribe with a unique id and a GraphQL document.
5. Server → one or more next messages, then complete.

Subscribe#

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription($t: ID!) { priceTicks(tokenId: $t) { tokenId price } }",
    "variables": { "t": "<tokenId>" }
  }
}

Data message#

{
  "id": "1",
  "type": "next",
  "payload": { "data": { "priceTicks": { "tokenId": "tok_123", "price": "0.0123" } } }
}

Unsubscribe#

Send a complete message to stop a single subscription; close the socket to end all.

{ "id": "1", "type": "complete" }

Errors#

Operation-level errors arrive as an error message for the matching id:

{ "id": "1", "type": "error", "payload": [{ "message": "Token not found" }] }

Connections that fail to send connection_init within 10 seconds are closed with code 4408 (Connection initialisation timeout).