Introducción#

La API de Catapult impulsa una plataforma de derivados de tokens sintéticos —operativa y datos de tokens— a través de un único endpoint GraphQL para operaciones petición/respuesta, y un endpoint WebSocket para suscripciones en tiempo real.

Endpoints base#

Todas las solicitudes HTTP usan POST con un cuerpo JSON con la forma { "query": "...", "variables": { ... } }.

Autenticación#

Las operaciones autenticadas usan un token JWT (bearer), enviado en la cabecera Authorization:

Authorization: Bearer <your-jwt-token>

El token es un JSON Web Token (JWT), válido por 730 días (≈2 años) desde su emisión por defecto: rótalo antes de que caduque. Solo ping es público; el resto de operaciones requiere el token bearer, y las lecturas como tokens y turboToken también necesitan el permiso tokens.read.

Crear una clave API#

Genera tu token desde el panel de tu cuenta en catapult.trade/settings/api-key (Ajustes → API Key). Puedes gestionar tu cuenta en catapult.trade.

Convenciones#

• Los IDs son cadenas opacas; no los parsees.
• Los importes monetarios son enteros codificados como cadena de tipo String! (p. ej. balanceUsdtDrops): parséalos como BigInt, nunca como float. El único escalar personalizado es DateTime.
• Las marcas de tiempo usan el escalar DateTime (ISO-8601, UTC).
• Las consultas de listas se paginan por cursor mediante input.pagination: limit (10 por defecto) con afterCursor / beforeCursor.

Ejemplo rápido#

query Tokens {
  # consulta la pestaña Reference para PublicTokenListInput y los campos del token
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

OAuth de clave API#

Este enlace te permite obtener la clave API de un usuario para crear distintas funciones, por ejemplo copy trading. El usuario concede los permisos sobre su clave API y esta se envía a tu URL de callback incluida en la lista blanca.

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

Reemplaza <WHITELISTED_BOT_ID> por el ID de tu bot incluido en la lista blanca.

Inclusión del bot en la lista blanca#

Incluye tu bot en la lista blanca contactando con nuestro equipo de desarrollo:

[email protected]

Unidades y convenciones#

Lee esto primero: cada campo monetario de la API depende de estas convenciones.

USDT drops (*UsdtDrops)#

Todos los importes en USDT son enteros de USDT × 1,000,000 (6 decimales), con el sufijo UsdtDrops. Se envían como String! (enteros codificados como cadena): parséalos como BigInt, nunca como float.

Convierte con usdt = drops / 1e6 y drops = round(usdt × 1e6): calcula en BigInt.

Apalancamiento (leverageX10)#

El apalancamiento se codifica como apalancamiento × 10. leverageX10: 125 significa 12.5×; 30 significa 3×.

Colateral vs nocional#

notional = collateral × leverage. Lo que aportas es el colateral; el valor nominal de la posición en USDT es el nocional.

Al abrir una posición, el importe es colateral, antes de comisión. tradeOpen toma exactamente uno de usdtDrops (en USDT) o amountWei (en tokens): el motor deriva el nocional a partir de él y del apalancamiento. No es el nocional.

Saldos#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

Medios del token (fileId)#

La imagen de un token se adjunta pasando un fileId a tokenCreate. Hay dos formas de obtenerlo:

1. Aleatorizador — tokenRandomizedPreset devuelve un fileId listo para usar (además de nombre, símbolo, modo, etc.) que puedes pasar directamente a tokenCreate.
2. Subida propia — un flujo S3 presigned-POST de tres pasos:
   • fileUpload(input) → devuelve una URL S3 presigned-POST más los campos de formulario que el cliente debe incluir en el POST multipart.
   • El cliente hace POST de la imagen a esa URL de S3 con esos campos exactos.
   • fileFinalize(id) → marca la subida como finalizada tras el POST a S3 y devuelve la URL pública del archivo; usa el archivo resultante como imagen del token.

Límites de subida: solo JPEG o PNG, máximo 5 MB, mínimo 314×314 px. El POST prefirmado debe completarse en 15 segundos tras la llamada a fileUpload, y las subidas están limitadas a 200 por hora por IP.

Modos de velocidad de tokens#

Cada token funciona en uno de cinco modos de velocidad. El campo de creación/aleatorización es turboTokenMode; los registros de token exponen speedMode. SLOW y NORMAL son el mismo modo con dos nombres.

Los valores de apalancamiento máximo y de vida útil siguientes son configuración actual que puede cambiar en el servidor: trátalos como valores actuales y verifícalos con la consulta de leverage-config en vivo.

El apalancamiento máximo es un límite fijo del motor#

El apalancamiento máximo de cada modo es un límite estricto que aplica el motor: usa el valor de la tabla directamente. El motor rechaza cualquier orden por encima.

Comisiones y tamaño de posición#

Comisión de apertura (~1%)#

Abrir una posición cobra una comisión de apertura de ~1% (0.01), deducida del colateral que envías:

collateral_post_fee = collateral_sent × (1 − fee)

Para que el colateral bloqueado quede exactamente en notional / leverage, envía:

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

Límite de nocional por posición#

El servidor aplica un límite de nocional por posición: actualmente 20,000 USDT por (token, apalancamiento, lado). Superarlo devuelve Maximum notional limit … exceeded. Verifica el valor exacto con la configuración en vivo; puede variar según el modo o el apalancamiento.

Posición máxima disponible (nocional)#

Sea fee = 0.01, free = balanceUsdtDrops / 1e6, inPos = inPositionsBalanceUsdtDrops / 1e6, capTotal = tu límite total de colateral opcional, capPos = límite de nocional por posición (~20,000), L = apalancamiento:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # si aplicas un límite total
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

Colateral a enviar = (maxPositionNotional / L) / (1 − fee).

Trampa de redondeo. Tras dividir por (1 − fee), un round(collateral × 1e6) ingenuo supera el límite por unos drops y la apertura se rechaza. Redondea hacia abajo el colateral en drops (BigInt) a un paso pequeño (p. ej. 10 drops = 0.00001 USDT) antes de enviar. Pierdes una fracción insignificante de céntimo y te mantienes bajo el límite en cualquier apalancamiento.

Ejemplo resuelto#

FLASH, 3×, comisión 1%, límite 20,000 de nocional:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (redondeado hacia abajo en drops)
→ bloqueado tras comisión ≈ 6,666.67, nocional ≈ 20,000

Códigos de estado#

Las respuestas GraphQL devuelven HTTP 200 incluso cuando una operación falla: inspecciona el array errors[] y el extensions.code de cada error. Los problemas de transporte usan códigos HTTP estándar.

Códigos de estado HTTP#

El servicio GraphQL devuelve los fallos de autenticación, permisos y límite de tasa dentro de la respuesta como 200 (ver códigos de error GraphQL). Los 401 / 403 / 429 de transporte solo ocurren si un gateway/CDN upstream rechaza la solicitud antes de llegar a la API.

Códigos de error GraphQL#

Los códigos distinguen mayúsculas; coincide con la cadena exacta. Los códigos de dominio son PascalCase (p. ej. RateLimited); algunos códigos del framework van en mayúsculas con guion bajo (p. ej. UNAUTHENTICATED).

Forma del error#

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

Límites de uso#

Las operaciones GraphQL comparten un único bucket de límite, indexado por token de API (jti) e IP: 600 consultas/min y 60 mutaciones/min. Al superar un límite se devuelve una respuesta HTTP 200 cuyo errors[] contiene un único error con extensions.code = RateLimited. La API no envía un estado 429 ni una cabecera Retry-After; las sugerencias de reintento se incluyen en extensions del error.

Límites HTTP (GraphQL)#

Límites de WebSocket#

Los límites de WebSocket son configurables en el servidor, por lo que en producción pueden diferir de estos valores por defecto. Se aplican por conexión, no por IP.

Cabeceras de respuesta#

La API no emite cabeceras de límite (X-RateLimit-*, Retry-After). Un gateway upstream podría añadirlas; no dependas de ellas.

Trampas e idempotencia#

Una lista de lo que los integradores suelen equivocar.

Dinero y dimensionamiento#

• Los drops son enteros: BigInt de principio a fin; nunca parsees *UsdtDrops como float.
• El importe de apertura que envías (usdtDrops o amountWei) es colateral, antes de comisión, no el nocional.
• El límite de nocional se aplica en drops; redondea hacia abajo tu colateral para evitar superarlo por unos drops (ver «Comisiones y tamaño de posición»).
• El apalancamiento máximo es un límite fijo del motor por modo (ver «Modos de velocidad de tokens»): úsalo directamente.

Tokens#

• El aleatorizador devuelve un rank aleatorio (Competition | Private | Public). Fuerza Public si el token debe listarse / poder copiarse.
• tokenCreate siempre usa pago desde el saldo: el tipo de pago no se puede anular.
• No hay una marca de «activo» en el servidor para tokens: filtra en el cliente por endDate.

Apertura y cierre#

• tradeOpen requiere exactamente uno de usdtDrops (en USDT) o amountWei (en tokens): nunca ambos ni ninguno.
• tradeClose cierra una posición abierta mediante USER_SELL.

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

• tradeLimitCreate requiere al menos un disparador (SL o TP).
• En update, un null explícito para un lado lo borra; un campo omitido se conserva.
• tradeLimitUpdate rechaza una entrada totalmente nula (Validation failed: input=MissingValue): usa tradeLimitDelete para borrar.
• No hay borrado por lado; tradeLimitDelete elimina ambos, TP y SL.

Suscripciones (WebSocket)#

• Autentícate en connection_init con payload: { Authorization: "Bearer <apiKey>" }.
• La suscripción positions transmite la unión PublicPositionEvent — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent. Discrimina por el campo type antes de leer los campos específicos del evento.
• PublicPositionClosedEvent lleva positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops. Los campos buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10 pertenecen a PublicPositionOpenedEvent, no al de cierre.
• Los eventos de cierre son at-least-once y no se reproducen. Un cierre emitido mientras te reconectas lo pierde la nueva suscripción: sondea cada posición abierta al (re)suscribirte para detectar cierres perdidos y deduplica por positionId.

API WebSocket#

Los datos en tiempo real se entregan por una conexión WebSocket usando el protocolo GraphQL sobre WebSocket (graphql-transport-ws). Úsalo para operaciones de tipo subscription, como las actualizaciones de precio en vivo.

Conexión#

Abre un WebSocket en:

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

Negocia el subprotocolo graphql-transport-ws. Tras abrir el socket, envía un mensaje connection_init; el servidor responde con connection_ack.

Ciclo de vida#

1. El cliente abre el socket con el subprotocolo graphql-transport-ws.
2. Cliente → {"type":"connection_init"}.
3. Servidor → {"type":"connection_ack"}.
4. Cliente → subscribe con un id único y un documento GraphQL.
5. Servidor → uno o varios mensajes next, después complete.

Suscripción#

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

Mensaje de datos#

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

Cancelar suscripción#

Envía un mensaje complete para detener una suscripción; cierra el socket para detenerlas todas.

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

Errores#

Los errores a nivel de operación llegan como un mensaje error para el id correspondiente:

{ "id": "1", "type": "error", "payload": [{ "message": "Mercado desconocido" }] }

Las conexiones que no envían connection_init en 10 segundos se cierran con el código 4408 (tiempo de inicialización agotado).