> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

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](/api-reference/supported-chains/). 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

```json theme={null}
{
  "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

<Note>
  **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.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Redes suportadas" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="Políticas e segurança" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>