Pular para o conteúdo principal

​
title: ‘AFK API v1’ description: ‘Visão geral e convenções da AFK Crypto API v1’

​
Visão geral

  • Caminho base: /api/v1
  • Autenticação: chave de API via cabeçalho x-api-key
  • Idempotência: endpoints de escrita requerem cabeçalho Idempotency-Key (UUID)
  • Formato de resposta: todas as respostas incluem o cabeçalho x-request-id para rastreamento

​
Endpoints

  • GET /api/v1/wallets – Listar carteiras do usuário
  • GET /api/v1/wallets/balances – Saldos da carteira do chamador (por chain; usa a carteira padrão)
  • GET /api/v1/wallets/:address/balances – Saldos para um endereço de carteira próprio específico
  • GET /api/v1/tx/:id – Detalhes de transação
  • POST /api/v1/send – Enviar ativos nativos e tokens (EVM + Solana)
  • POST /api/v1/token/approve – Aprovação de token ERC20 (somente EVM)
  • POST /api/v1/contracts/send – Interação genérica com contratos (somente EVM)
  • POST /api/v1/trade/quote – Obter cotações de swap (EVM + Solana)
  • POST /api/v1/trade/swap – Executar swaps (EVM + Solana)

​
Chains

Veja a lista completa em Redes suportadas. Use o slug chain (por exemplo, base, solana-devnet).

​
Limitação de taxa

  • Escritas (incluindo POST /api/v1/trade/quote): 15 requisições por minuto por usuário
  • Leituras: 60 requisições por minuto por usuário
  • Resposta: HTTP 429 quando excedido
  • Cabeçalhos: Retry-After (segundos até a próxima janela)

​
Idempotência (escritas)

  • Todos os endpoints mutáveis exigem Idempotency-Key.
  • Reutilizar a chave com o mesmo corpo retorna a resposta 200 original.
  • Reutilizar a chave com corpo diferente retorna HTTP 409 com code: IDEMPOTENT_BODY_MISMATCH.
  • Reutilizar a chave sem resposta de sucesso armazenada retorna HTTP 409 com code: IDEMPOTENT_REPLAY.
  • As chaves são vinculadas ao usuário autenticado; o caminho do endpoint é registrado para rastreio.
  • Aplica-se a: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
Tratamento de erros

​
Formato de erro

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
Códigos de erro

  • UNAUTHORIZED – Autenticação ausente/inválida ou chave de API (HTTP 401)
  • FORBIDDEN – Autenticado mas sem permissão para realizar a ação (HTTP 403)
  • NOT_FOUND – Recurso não encontrado (HTTP 404)
  • RATE_LIMITED – Limite de taxa excedido (HTTP 429)
  • INVALID_INPUT – Parâmetros de solicitação inválidos (HTTP 400)
  • WALLET_NOT_FOUND – Carteira especificada não encontrada
  • USER_NOT_LINKED – Usuário não vinculado ao Privy
  • WALLET_NOT_DELEGATED – Carteira não delegada ao assinante do servidor
  • WALLET_ID_REQUIRED – ID de carteira Privy ausente
  • CHAIN_UNKNOWN – Chain desconhecida ou não suportada
  • INSUFFICIENT_FUNDS – Remetente sem fundos para valor/taxa
  • IDEMPOTENT_BODY_MISMATCH – Corpo de solicitação diferente com a mesma chave de idempotência (HTTP 409)
  • IDEMPOTENT_REPLAY – Chave de idempotência já utilizada (HTTP 409)
  • PRIVY_RPC_ERROR – Erro do serviço RPC Privy
  • SEND_FAILED – Falha no envio da transação
  • SERVICE_UNAVAILABLE – Serviço necessário não configurado
  • QUOTE_FAILED – Erro do serviço de cotação (HTTP 400)
  • INTERNAL_ERROR – Erro do servidor
Detalhes do QUOTE_FAILED:
  • Solana/Jupiter: Alguns mints Solana não são negociáveis no Jupiter (lista permitida). Nesses casos, esta API retorna HTTP 400 com code: QUOTE_FAILED e uma mensagem de erro como: “Token not tradable on Jupiter”.
  • EVM/1inch: Se um token não é suportado pelo 1inch, a API retorna HTTP 400 com code: QUOTE_FAILED e uma mensagem como: “Token not tradable on 1inch”.
  • Isso é esperado quando o token/mint de saída solicitado está marcado como não negociável pelo provedor upstream, mesmo que existam pools em outros lugares.

​
Validações

​
Formatos de endereço

  • EVM: deve corresponder a /^0x[a-fA-F0-9]{40}$/
  • Solana: deve ser uma chave pública base58 válida

​
Parâmetros comuns

  • Valores (EVM): Apenas strings inteiras (decimal ou 0x-hex). Devem ser não negativos. Para ERC20 e value, devem caber em uint256.
  • Valores (Solana): Strings inteiras em unidades base. Valores SPL devem caber em faixa sem sinal de 64 bits.
  • Remetente (from): Opcional. Se omitido, usa a carteira padrão do usuário para a chain especificada.
  • Idempotência: Todos os endpoints de escrita exigem cabeçalho Idempotency-Key. Repetições com o mesmo corpo retornam a resposta original.

​
Palavra-chave de token nativo

Os endpoints de negociação (/api/v1/trade/quote, /api/v1/trade/swap) aceitam a palavra-chave NATIVE (insensível a maiúsculas/minúsculas) para fromToken/toToken:
  • EVM: NATIVE é resolvido para 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana: NATIVE é resolvido para o mint SOL encapsulado So11111111111111111111111111111111111111112
  • As respostas retornam endereços resolvidos (não NATIVE)
  • O endpoint de envio usa asset: "native" em vez de endereços de token para transferências nativas

​
Convenções

  • Seleção de chain: use o slug chain (por exemplo, base, base-sepolia, solana-devnet).
  • Mapeamento sentinela de Transaction.chainId em Solana: 0 = mainnet, -2 = testnet, -3 = devnet.
  • Idempotência: única por usuário e chave; repetições retornam a resposta original; corpos divergentes → 409.

​
Relacionados

Redes suportadas

Políticas e segurança