Visão geral#

A API da Catapult alimenta uma plataforma de derivativos de tokens sintéticos — negociação e dados de tokens — através de um único endpoint GraphQL para operações de requisição/resposta e um endpoint WebSocket para assinaturas em tempo real.

Endpoints base#

Todas as requisições HTTP usam POST com um corpo JSON no formato { "query": "...", "variables": { ... } }.

Autenticação#

As operações autenticadas usam um token JWT (bearer), enviado no cabeçalho Authorization:

Authorization: Bearer <your-jwt-token>

O token é um JSON Web Token (JWT), válido por 730 dias (≈2 anos) a partir da emissão por padrão — rotacione-o antes de expirar. Apenas ping é público; todas as outras operações exigem o token bearer, e leituras como tokens e turboToken também precisam da permissão tokens.read.

Criar uma chave de API#

Gere seu token no painel da sua conta em catapult.trade/settings/api-key (Configurações → API Key). Você pode gerenciar sua conta em catapult.trade.

Convenções#

• Os IDs são strings opacas; não os parseie.
• Os valores monetários são inteiros codificados como string do tipo String! (ex.: balanceUsdtDrops) — parseie-os como BigInt, nunca como float. O único scalar personalizado é DateTime.
• Os timestamps usam o scalar DateTime (ISO-8601, UTC).
• As consultas de listas são paginadas por cursor via input.pagination: limit (padrão 10) com afterCursor / beforeCursor.

Exemplo rápido#

query Tokens {
  # veja a aba Reference para o PublicTokenListInput completo e os campos do token
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

OAuth de chave de API#

Este link permite obter a chave de API de um usuário para criar diversos recursos, por exemplo copy trading. O usuário concede as permissões à sua chave de API, e ela é enviada para a sua URL de callback na lista de permissões.

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

Substitua <WHITELISTED_BOT_ID> pelo ID do seu bot na lista de permissões.

Lista de permissões do bot#

Coloque seu bot na lista de permissões entrando em contato com nossa equipe de desenvolvimento:

[email protected]

Unidades e convenções#

Leia isto primeiro: cada campo monetário da API depende destas convenções.

USDT drops (*UsdtDrops)#

Todos os valores em USDT são inteiros de USDT × 1,000,000 (6 casas decimais), com o sufixo UsdtDrops. São enviados como String! (inteiros codificados como string) — parseie-os como BigInt, nunca como float.

Converta com usdt = drops / 1e6 e drops = round(usdt × 1e6) — calcule em BigInt.

Alavancagem (leverageX10)#

A alavancagem é codificada como alavancagem × 10. leverageX10: 125 significa 12.5×; 30 significa 3×.

Colateral vs nocional#

notional = collateral × leverage. O que você aporta é o colateral; o valor de face da posição em USDT é o nocional.

Ao abrir uma posição, o valor é colateral, antes da taxa. tradeOpen aceita exatamente um de usdtDrops (em USDT) ou amountWei (em tokens) — o motor deriva o nocional a partir dele e da alavancagem. Não é o nocional.

Saldos#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

Mídia do token (fileId)#

A imagem de um token é anexada passando um fileId para tokenCreate. Há duas formas de obter um:

1. Randomizador — tokenRandomizedPreset retorna um fileId pronto para uso (além de nome, símbolo, modo, etc.) que você pode passar direto para tokenCreate.
2. Upload próprio — um fluxo S3 presigned-POST de três etapas:
   • fileUpload(input) → retorna uma URL S3 presigned-POST mais os campos de formulário que o cliente deve incluir no POST multipart.
   • O cliente faz POST da imagem para essa URL do S3 com esses campos exatos.
   • fileFinalize(id) → marca o upload como concluído após o POST no S3 e retorna a URL pública do arquivo; use o arquivo resultante como imagem do token.

Limites de upload: apenas JPEG ou PNG, máximo 5 MB, mínimo 314×314 px. O POST pré-assinado deve concluir em 15 segundos após a chamada fileUpload, e os uploads são limitados a 200 por hora por IP.

Modos de velocidade de tokens#

Cada token funciona em um de cinco modos de velocidade. O campo de criação/randomização é turboTokenMode; os registros de token expõem speedMode. SLOW e NORMAL são o mesmo modo com dois nomes.

Os valores de alavancagem máxima e de tempo de vida abaixo são configuração atual que pode mudar no servidor — trate-os como valores atuais e verifique na consulta de leverage-config ao vivo.

A alavancagem máxima é um limite fixo do motor#

A alavancagem máxima de cada modo é um limite rígido aplicado pelo motor — use o valor da tabela diretamente. O motor rejeita qualquer ordem acima dele.

Taxas e tamanho da posição#

Taxa de abertura (~1%)#

Abrir uma posição cobra uma taxa de abertura de ~1% (0.01), deduzida do colateral que você envia:

collateral_post_fee = collateral_sent × (1 − fee)

Para que o colateral bloqueado fique exatamente em notional / leverage, envie:

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

Limite de nocional por posição#

O servidor aplica um limite de nocional por posição — atualmente 20,000 USDT por (token, alavancagem, lado). Excedê-lo retorna Maximum notional limit … exceeded. Verifique o valor exato na configuração ao vivo; pode variar por modo ou alavancagem.

Posição máxima disponível (nocional)#

Seja fee = 0.01, free = balanceUsdtDrops / 1e6, inPos = inPositionsBalanceUsdtDrops / 1e6, capTotal = seu limite total de colateral opcional, capPos = limite de nocional por posição (~20,000), L = alavancagem:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # se você aplicar um limite total
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

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

Pegadinha de arredondamento. Após dividir por (1 − fee), um round(collateral × 1e6) ingênuo ultrapassa o limite por alguns drops e a abertura é rejeitada. Arredonde para baixo o colateral em drops (BigInt) para um passo pequeno (ex.: 10 drops = 0.00001 USDT) antes de enviar. Você perde uma fração insignificante de centavo e fica abaixo do limite em qualquer alavancagem.

Exemplo resolvido#

FLASH, 3×, taxa 1%, limite 20,000 de nocional:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (arredondado para baixo em drops)
→ bloqueado após taxa ≈ 6,666.67, nocional ≈ 20,000

Códigos de status#

As respostas GraphQL retornam HTTP 200 mesmo quando uma operação falha — inspecione o array errors[] e o extensions.code de cada erro. Problemas de transporte usam códigos HTTP padrão.

Códigos de status HTTP#

O serviço GraphQL retorna falhas de autenticação, permissão e limite de taxa dentro da resposta como 200 (ver códigos de erro GraphQL). Os 401 / 403 / 429 de transporte só ocorrem se um gateway/CDN upstream rejeitar a requisição antes de chegar à API.

Códigos de erro GraphQL#

Os códigos diferenciam maiúsculas; corresponda à string exata. Códigos de domínio são PascalCase (ex.: RateLimited); alguns códigos do framework usam maiúsculas com sublinhado (ex.: UNAUTHENTICATED).

Formato do erro#

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

Limites de uso#

As operações GraphQL compartilham um único bucket de limite, indexado por token de API (jti) e IP: 600 consultas/min e 60 mutações/min. Ao exceder um limite, retorna uma resposta HTTP 200 cujo errors[] contém um único erro com extensions.code = RateLimited. A API não envia status 429 nem cabeçalho Retry-After; dicas de tempo de retry vêm em extensions do erro.

Limites HTTP (GraphQL)#

Limites de WebSocket#

Os limites de WebSocket são configuráveis no servidor, portanto a produção pode diferir destes padrões. São aplicados por conexão, não por IP.

Cabeçalhos de resposta#

A API não emite cabeçalhos de limite (X-RateLimit-*, Retry-After). Um gateway upstream pode adicioná-los; não dependa deles.

Pegadinhas e idempotência#

Uma lista do que os integradores mais erram.

Dinheiro e dimensionamento#

• Drops são inteiros — BigInt de ponta a ponta; nunca faça parse de *UsdtDrops como float.
• O valor de abertura que você envia (usdtDrops ou amountWei) é colateral, antes da taxa, não o nocional.
• O limite de nocional é aplicado em drops; arredonde para baixo seu colateral para evitar ultrapassar por alguns drops (ver «Taxas e tamanho da posição»).
• A alavancagem máxima é um limite fixo do motor por modo (ver «Modos de velocidade de tokens») — use-o diretamente.

Tokens#

• O randomizador retorna um rank aleatório (Competition | Private | Public). Force Public se o token precisar ser listado / copiável.
• tokenCreate sempre usa pagamento por saldo — o tipo de pagamento não pode ser sobrescrito.
• Não há flag de "ativo" no servidor para tokens — filtre no cliente por endDate.

Abertura e fechamento#

• tradeOpen exige exatamente um de usdtDrops (em USDT) ou amountWei (em tokens) — nunca ambos, nunca nenhum.
• tradeClose fecha uma posição aberta via USER_SELL.

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

• tradeLimitCreate exige pelo menos um gatilho (SL ou TP).
• No update, um null explícito para um lado o limpa; um campo omitido é preservado.
• tradeLimitUpdate rejeita uma entrada totalmente nula (Validation failed: input=MissingValue) — use tradeLimitDelete para limpar.
• Não há exclusão por lado; tradeLimitDelete remove ambos, TP e SL.

Assinaturas (WebSocket)#

• Autentique no connection_init com payload: { Authorization: "Bearer <apiKey>" }.
• A assinatura positions transmite a união PublicPositionEvent — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent. Verifique o campo type antes de ler os campos específicos do evento.
• PublicPositionClosedEvent carrega positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops. Os campos buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10 pertencem ao PublicPositionOpenedEvent, não ao de fechamento.
• Os eventos de fechamento são at-least-once e não são reenviados. Um fechamento emitido enquanto você reconecta é perdido pela nova assinatura — consulte cada posição aberta ao (re)assinar para detectar fechamentos perdidos e deduplique por positionId.

API WebSocket#

Os dados em tempo real são entregues por uma conexão WebSocket usando o protocolo GraphQL over WebSocket (graphql-transport-ws). Use-o para operações de subscription, como atualizações de preço ao vivo.

Conexão#

Abra um WebSocket em:

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

Negocie o subprotocolo graphql-transport-ws. Depois que o socket abrir, envie uma mensagem connection_init; o servidor responde com connection_ack.

Ciclo de vida#

1. O cliente abre o socket com o subprotocolo graphql-transport-ws.
2. Cliente → {"type":"connection_init"}.
3. Servidor → {"type":"connection_ack"}.
4. Cliente → subscribe com um id único e um documento GraphQL.
5. Servidor → uma ou mais mensagens next, depois complete.

Assinatura#

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

Mensagem de dados#

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

Cancelar assinatura#

Envie uma mensagem complete para parar uma assinatura; feche o socket para parar todas.

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

Erros#

Os erros no nível da operação chegam como uma mensagem error para o id correspondente:

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

Conexões que não enviam connection_init em 10 segundos são fechadas com o código 4408 (tempo de inicialização da conexão esgotado).