Documentação da API

Use com sua IA

Conecte o seu assistente (ChatGPT, Claude, Cursor ou outro) à API em um passo. O prompt abaixo já leva as regras que mais quebram integrações e aponta a documentação em formato para LLMs.

Você vai me ajudar a integrar a API v2 da SwapDAO (https://SEU_DOMINIO).
Leia primeiro a documentação para LLMs em https://SEU_DOMINIO/llms-full.txt e o contrato OpenAPI em https://SEU_DOMINIO/openapi.json.

Regras obrigatórias:
1. Autentique toda requisição com o header X-Api-Key (ou Authorization: Bearer) com a chave da conta; nunca exponha a chave no navegador, em código público ou em conversa.
2. Valores são strings de inteiro canônico nas unidades mínimas do ativo (sem ponto, sinal ou zeros à esquerda). DePix tem precisão 8: 100 DePix = "10000000000".
3. Comece pelo catálogo (GET /api/v2/catalog) e use só rotas com enabled: true, respeitando minUnits, maxUnits, memoRequired e a precisão dos ativos.
4. A cotação (POST /api/v2/quotes) é uma estimativa válida por até 5 minutos; refaça quando expirar. estimatedDestinationUnits não é garantido.
5. Crie a operação (POST /api/v2/orders) com o corpo exato {"quoteId": "..."} e um header Idempotency-Key único; repita a MESMA chave após falha de rede e nunca crie outra operação por causa de timeout (recupere com GET /api/v2/orders?quoteId=...).
6. A operação só avança quando o depósito chega: siga paymentInstructions (ativo, rede, endereço e valor exato) e acompanhe por GET /api/v2/orders/{orderId} usando state como fonte de verdade.
7. Na rota DePix → Pix (crypto_pix:depix:liquid:pix) envie payoutAmountUnits em centavos de real (não amountUnits), destination.address com CPF/CNPJ ou a chave Pix com pixKeyType e taxNumber, e Idempotency-Key também na cotação.
8. Chaves de API não cotam fluxos com entrada Pix (PIX_CRYPTO, PIX_DEPIX). Erros vêm como {error, code}: decida pelo status HTTP e pelo code; em 429 respeite Retry-After.

Use SUA_CHAVE_DA_CONTA como placeholder da chave e leia o valor real de uma variável de ambiente (ex.: DEPIX_API_KEY).
Antes de escrever código, confirme comigo a linguagem, a rota e o fluxo que vou usar.

Documentação legível por máquina, para colar o link em qualquer assistente ou ferramenta:

Servidor MCP

Agentes compatíveis com o Model Context Protocol usam a API como ferramentas, com a sua chave e as mesmas regras, quotas e escopos. Endereço (Streamable HTTP): https://SEU_DOMINIO/mcp. Envie a chave no header X-Api-Key; prefira uma chave dedicada, com só os escopos necessários.

claude mcp add --transport http swapdao https://SEU_DOMINIO/mcp --header "X-Api-Key: SUA_CHAVE_DA_CONTA"

Nenhuma ferramenta movimenta dinheiro: create_order só gera as instruções de depósito, e a operação avança quando o depósito chega. Repetir create_order com o mesmo quoteId é seguro. Os clientes pedem confirmação antes de ferramentas que alteram estado.

Integração pela sua conta

A API v2 associa cada requisição à conta dona da chave e aplica as permissões, a comissão e as condições comerciais da sua conta no servidor.

Chave e autenticação

Envie a mesma chave da conta em todas as etapas: catálogo, cotação, criação e consulta da operação. Use um dos headers abaixo. Nas requisições com corpo, envie também Content-Type: application/json.

X-Api-Key: SUA_CHAVE_DA_CONTA

# Alternativa ao header acima:
Authorization: Bearer SUA_CHAVE_DA_CONTA

Uma chave só pode usar seus próprios escopos, dentro das permissões e da disponibilidade dos fluxos. Se enviar os dois headers, eles precisam conter a mesma chave. Trate respostas 401/403 como falha de autenticação ou autorização e 429 como limite de requisições, respeitando o header Retry-After quando informado. Os escopos usam os nomes dos fluxos em minúsculas: depix_crypto, crypto_pix, crypto_depix, crypto_crypto, pix_depix e pix_crypto.

Cotação e criação da operação

1. Consulte o catálogo. Use uma rota com enabled: true e respeite minUnits, maxUnits, memoRequired e a precisão dos ativos retornados. confirmations informa quantas confirmações do depósito a rota exige. Com a sua chave, o catálogo já reflete os escopos dela.
2. Crie uma cotação. Informe routeId, amountUnits e destination. amountUnits é uma string de inteiro canônico (sem ponto, sinal ou zeros à esquerda) na precisão do ativo de entrada. Na rota direta DePix → Pix, informe payoutAmountUnits em centavos de Pix e uma Idempotency-Key, conforme a seção específica abaixo.
3. Crie a operação. Envie somente o quoteId retornado e um header Idempotency-Key próprio para essa criação, com 1 a 256 caracteres e sem caracteres de controle. Reutilize a mesma chave de idempotência ao repetir a mesma solicitação após uma falha de rede.
4. Acompanhe o resultado. Consulte o orderId retornado com a mesma credencial e siga as instruções de entrada da operação.

{
  "routeId": "depix_crypto:lbtc:liquid",
  "amountUnits": "10000000000",
  "destination": {
    "address": "ENDERECO_LIQUID_VALIDO"
  }
}

O exemplo representa 100 DePix quando source.precision é 8; só use essa rota se estiver habilitada no catálogo e o valor estiver dentro dos limites. Quando memoRequired é true, envie destination.memo; quando é false, não envie memo. Rotas com entrada por Pix (PIX_CRYPTO e PIX_DEPIX) não estão disponíveis para chaves de API: aparecem no catálogo com enabled: false e a cotação responde 403 flow_not_authorized. A resposta 201 contém quote.quoteId e quote.expiresAt. A cotação é uma estimativa válida por até 5 minutos (menos quando o prazo do provedor da rota é mais curto); uma cotação expirada precisa ser refeita. O prazo de pagamento/depósito da ordem (inputExpiresAt) é separado e, em geral, termina 30 minutos depois do fim da validade. quote.execution.estimatedDestinationUnits é uma estimativa (rateType floating), não um valor garantido.

Idempotency-Key: IDENTIFICADOR_UNICO_DA_CRIACAO
Content-Type: application/json

{
  "quoteId": "UUID_DA_COTACAO"
}

A criação responde 201 com orderId, state, snapshot e idempotentReplay: false. Repetir a mesma Idempotency-Key com o mesmo quoteId responde 200 com o mesmo resultado e idempotentReplay: true; a mesma chave com outro quoteId responde 409 idempotency_conflict. Se a resposta da criação se perder, GET /api/v2/orders?quoteId=UUID_DA_COTACAO permite localizar a operação com a mesma credencial. Nunca crie outra operação apenas porque houve timeout.

Taxas e comissão da sua conta

As condições comerciais são resolvidas pelo servidor a partir da conta vinculada à sua chave. Confira os valores retornados na cotação antes de criar a operação. A taxa total da plataforma é definida pelo servidor e não pode ser substituída no corpo da requisição.

DePix → Pix direto

Quando estiver habilitada no catálogo, a rota crypto_pix:depix:liquid:pix permite informar quanto você deseja receber em Pix. O cliente envia DePix diretamente ao endereço retornado nas instruções de depósito. A aplicação não cobra comissões próprias; o total a enviar inclui as tarifas externas da liquidação Pix, informadas na cotação.

Idempotency-Key: depix-pix-intencao-100-1
Content-Type: application/json

{
  "routeId": "crypto_pix:depix:liquid:pix",
  "payoutAmountUnits": "10000",
  "destination": {
    "address": "CPF_OU_CNPJ_VALIDO_DO_DESTINATARIO"
  }
}

Envie a solicitação a POST /api/v2/quotes. payoutAmountUnits representa o valor líquido em centavos de real. Não envie amountUnits nessa rota: o servidor calcula o total de DePix. Não envie payer, percentual de tarifa ou cupom. Omita commissionBps ou envie zero; comissão positiva e couponCode retornam 422, sem reserva de cupom. Opcionalmente, maxSourceAmountUnits limita o total de DePix aceito: se o total calculado passar dele, a resposta é 422 execution_source_budget_exceeded.

Nesta rota a Idempotency-Key da cotação é obrigatória e deve ter de 8 a 128 caracteres, começando por letra ou número e usando apenas letras, números, ponto, hífen, sublinhado ou dois-pontos; caso contrário a resposta é 400 idempotency_key_required. A mesma chave com outro conteúdo responde 409 idempotency_conflict.

Com destination.address igual ao CPF ou CNPJ, ele é usado como chave Pix e documento do destinatário. Para outra chave Pix, envie também pixKeyType (cpf, cnpj, email, phone ou random) e taxNumber com o CPF/CNPJ do titular. Nas chaves cpf e cnpj, a chave precisa ser o próprio taxNumber. Destinatário inválido responde 422 invalid_pix_recipient.

{
  "routeId": "crypto_pix:depix:liquid:pix",
  "payoutAmountUnits": "10000",
  "destination": {
    "address": "EMAIL_CHAVE_PIX_DO_DESTINATARIO",
    "pixKeyType": "email",
    "taxNumber": "CPF_OU_CNPJ_DO_TITULAR"
  }
}

Status e acompanhamento

GET /api/v2/orders/{orderId} responde { order } com id, quoteId, flow, state, version, snapshot, legs, paymentInstructions (enquanto houver depósito a fazer) e, quando disponível, progress. A ordem nunca expõe a forma interna de execução: legs contém apenas o depósito (input), a entrega (payout) e uma devolução (refund), e externalReference é o hash da sua transação on-chain ou null. Use state e version como fonte de verdade.

progress.steps segue cinco etapas públicas (awaiting_deposit, deposit_confirmed, converting, sending, completed), cada uma com status pending, active, done ou error. progress.issue aparece em análise, devolução ou expiração. Com a ordem em confirmed aguardando vaga de execução, progress.queue traz { queued: true, position } e a etapa converting indica queued e queuePosition. Valores reais podem ficar null até haver evidência.

Webhooks

Cadastre um destino HTTPS público com a própria chave em POST /api/v2/webhooks, corpo { endpointUrl, flows }, em que flows é uma lista de escopos da chave. A resposta 201 traz subscription e secret (whsec_…), exibido uma única vez. Use GET /api/v2/webhooks, GET, PATCH (endpointUrl, flows, rotateSecret) e DELETE em /api/v2/webhooks/{subscriptionId}para gerenciar. São até 10 destinos ativos por chave; só ordens criadas pela mesma chave são notificadas.

X-V2-Webhook-Id: UUID_DO_EVENTO
X-V2-Webhook-Event: order.updated
X-V2-Webhook-Timestamp: 1793908800
X-V2-Webhook-Signature: v1=HEX_HMAC_SHA256

{
  "id": "UUID_DO_EVENTO",
  "type": "order.updated",
  "createdAt": "2026-11-13T12:00:00.000Z",
  "data": {
    "orderId": "UUID_DA_OPERACAO",
    "flow": "DEPIX_CRYPTO",
    "status": "confirmed",
    "version": "3",
    "legs": [{ "id": "UUID", "position": 1, "kind": "input", "status": "confirmed",
      "asset": "DEPIX", "network": "LIQUID", "amountUnits": "10000000000", "actualAmountUnits": "10000000000" }]
  }
}

Verifique a assinatura com HMAC-SHA256 usando o segredo completo sobre `${timestamp}.${corpoBruto}`, compare em tempo constante e rejeite timestamps fora de uma janela curta. Deduplique pelo id: novas tentativas reutilizam o mesmo corpo e id. Responda 2xx para confirmar; outras respostas são repetidas com espera crescente (até 12 tentativas). O mesmo status pode chegar mais de uma vez, inclusive quando uma análise é encerrada; version é uma string decimal. Na dúvida, consulte a ordem.

Erros e limites

Erros usam o envelope { "error": "mensagem", "code": "codigo" }. Decida pelo status HTTP e pelo code; a mensagem é para pessoas e pode mudar. Códigos representativos:

Cada cotação, criação de operação (inclusive repetição idempotente) e chamada de webhooks consome a quota por minuto da chave. A criação também tem limite fixo de 20 por chave e 30 por IP por minuto. Consultas de operação (GET /api/v2/orders/…) não consomem a quota e têm limite próprio de 60 por chave e 120 por IP por minuto; uma chave revogada ainda consulta as próprias operações. Corpos: até 8 KiB na cotação e 2 KiB na criação da operação.