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

# AFK API v1

> Descripción general y convenciones para AFK Crypto API v1

## Descripción general

* Ruta base: `/api/v1`
* Autenticación: clave de API en encabezado `x-api-key`
* Idempotencia: las operaciones de escritura requieren encabezado `Idempotency-Key` (formato UUID)
* Formato de respuesta: todas las respuestas incluyen encabezado `x-request-id` para trazabilidad

### Endpoints

* `GET /api/v1/wallets` – Listar billeteras del usuario
* `GET /api/v1/wallets/balances` – Saldos de la billetera del llamador (por cadena; predetermina a la billetera por defecto)
* `GET /api/v1/wallets/:address/balances` – Saldos para una dirección de billetera propia específica
* `GET /api/v1/tx/:id` – Obtener detalles de una transacción
* `POST /api/v1/send` – Enviar activos nativos y tokens (EVM + Solana)
* `POST /api/v1/token/approve` – Aprobación de tokens ERC20 (solo EVM)
* `POST /api/v1/contracts/send` – Interacción genérica con contratos (solo EVM)
* `POST /api/v1/trade/quote` – Obtener cotizaciones de intercambio (EVM + Solana)
* `POST /api/v1/trade/swap` – Ejecutar intercambios (EVM + Solana)

## Cadenas

Vea la lista completa en [Cadenas soportadas](/api-reference/supported-chains/). Use el slug `chain` (por ejemplo, `base`, `solana-devnet`).

## Limitación de tasa

* **Escrituras** (incluyendo `POST /api/v1/trade/quote`): 15 solicitudes por minuto por usuario
* **Lecturas**: 60 solicitudes por minuto por usuario
* Respuesta: HTTP 429 cuando se excede
* Encabezados: `Retry-After` (segundos hasta la siguiente ventana)

## Idempotencia (escrituras)

* Todos los endpoints mutantes requieren `Idempotency-Key`.
* Reutilizar una clave con el mismo cuerpo devuelve la respuesta 200 original.
* Reutilizar una clave con un cuerpo distinto devuelve HTTP 409 con `code: IDEMPOTENT_BODY_MISMATCH`.
* Reutilizar una clave sin una respuesta exitosa almacenada devuelve HTTP 409 con `code: IDEMPOTENT_REPLAY`.
* Las claves están asociadas al usuario autenticado; se registra la ruta del endpoint.
* Aplica a: `POST /api/v1/send`, `POST /api/v1/token/approve`, `POST /api/v1/contracts/send`, `POST /api/v1/trade/swap`.

## Manejo de errores

### Formato de respuesta de error

```json theme={null}
{
  "error": "Mensaje de error legible",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}
```

### Códigos de error

* `UNAUTHORIZED` – Autenticación faltante/inválida o clave de API (HTTP 401)
* `FORBIDDEN` – Autenticado pero sin permiso para realizar la acción (HTTP 403)
* `NOT_FOUND` – Recurso no encontrado (HTTP 404)
* `RATE_LIMITED` – Límite de tasa excedido (HTTP 429)
* `INVALID_INPUT` – Parámetros de solicitud inválidos (HTTP 400)
* `WALLET_NOT_FOUND` – Billetera especificada no encontrada
* `USER_NOT_LINKED` – Usuario no vinculado a Privy
* `WALLET_NOT_DELEGATED` – Billetera no delegada al firmante del servidor
* `WALLET_ID_REQUIRED` – Falta ID de billetera Privy
* `CHAIN_UNKNOWN` – Cadena desconocida o no soportada
* `INSUFFICIENT_FUNDS` – El remitente carece de fondos para valor/tarifa
* `IDEMPOTENT_BODY_MISMATCH` – Cuerpo de solicitud diferente con la misma clave de idempotencia (HTTP 409)
* `IDEMPOTENT_REPLAY` – Clave de idempotencia ya utilizada (HTTP 409)
* `PRIVY_RPC_ERROR` – Error del servicio RPC de Privy
* `SEND_FAILED` – Envío de transacción fallido
* `SERVICE_UNAVAILABLE` – Servicio requerido no configurado
* `QUOTE_FAILED` – Error del servicio de cotización (HTTP 400)
* `INTERNAL_ERROR` – Error del servidor

<Note>
  **Detalles de QUOTE\_FAILED:**

  * **Solana/Jupiter**: Algunos mints de Solana no son comerciables en Jupiter (lista permitida curada). En esos casos, esta API devuelve HTTP 400 con `code: QUOTE_FAILED` y un mensaje de error como: "Token not tradable on Jupiter".
  * **EVM/1inch**: Si un token no es soportado por 1inch, la API devuelve HTTP 400 con `code: QUOTE_FAILED` y un mensaje como: "Token not tradable on 1inch".
  * Esto es esperado cuando el token/mint de salida solicitado está marcado como no comerciable por el proveedor upstream, incluso si existen pools en otros lugares.
</Note>

## Validación

### Formatos de dirección

* EVM: debe coincidir con `/^0x[a-fA-F0-9]{40}$/`
* Solana: debe ser una clave pública base58 válida

### Parámetros comunes

* **Montos (EVM)**: Solo cadenas enteras (decimal o 0x-hex). Deben ser no negativos. Para ERC20 y `value`, deben caber en uint256.
* **Montos (Solana)**: Cadenas enteras en unidades base. Los montos SPL deben caber en rango sin signo de 64 bits.
* **Remitente (`from`)**: Opcional. Si se omite, se usa la billetera predeterminada del usuario para la cadena especificada.
* **Idempotencia**: Todos los endpoints de escritura requieren encabezado `Idempotency-Key`. Las repeticiones con el mismo cuerpo devuelven la respuesta original.

### Palabra clave de token nativo

Los endpoints de intercambio (`/api/v1/trade/quote`, `/api/v1/trade/swap`) aceptan la palabra clave `NATIVE` (sin distinción de mayúsculas/minúsculas) para `fromToken`/`toToken`:

* **EVM**: `NATIVE` se resuelve a `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`
* **Solana**: `NATIVE` se resuelve al mint de SOL envuelto `So11111111111111111111111111111111111111112`
* Las respuestas devuelven direcciones resueltas (no `NATIVE`)
* El endpoint de envío usa `asset: "native"` en lugar de direcciones de token para transferencias nativas

## Convenciones

* Selección de cadena: use el slug `chain` (p. ej., `base`, `base-sepolia`, `solana-devnet`).
* Mapeo de sentinelas para `Transaction.chainId` en Solana: `0` = mainnet, `-2` = testnet, `-3` = devnet.
* Idempotencia: única por usuario y clave; repeticiones devuelven la respuesta original; cuerpos distintos → 409.

## Relacionado

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

  <Card title="Políticas y seguridad" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>