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

# Introducción a la API

> Documentación completa de pan API v1

Bienvenido a la referencia de pan API. Esta documentación describe todos los endpoints disponibles, formatos de request/response, códigos de error, y métodos de autenticación.

## URL Base

Todas las requests deben hacerse a:

```
https://api.pan.tech/v1
```

<Note>
  **Entorno de staging**: Para pruebas, usa `https://api-staging.pan.tech/v1`. Staging usa solo testnets y está aislado de produccion.
</Note>

## Autenticación

Todos los endpoints requieren autenticación usando una API key. Incluye tu API key en el header `Authorization`:

```bash theme={null}
Authorization: Bearer pan_sk_tu_api_key
```

<Warning>
  Manten tu API key secreta. Nunca la expongas en código del lado del cliente o repositorios publicos. Ver [guia de autenticación](/guias/autenticación).
</Warning>

## Versionado

pan API usa versionado basado en URL. La version actual es `v1`, incluida en la URL base. Versiones futuras usaran paths diferentes (ej. `/v2/`) para mantener compatibilidad hacia atras.

## Formato de Requests

Todas las requests deben usar:

* **Metodo**: Métodos HTTP (GET, POST, etc.)
* **Content-Type**: `application/json` para bodies
* **Encoding**: UTF-8

## Formato de Respuestas

Todas las respuestas retornan JSON:

<AccordionGroup>
  <Accordion title="Respuestas exitosas">
    Respuestas exitosas (codigos 2xx) retornan el recurso directamente:

    ```json theme={null}
    {
      "id": "pan_wallet_abc123",
      "userId": "usuario_123",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      ...
    }
    ```
  </Accordion>

  <Accordion title="Respuestas de error">
    Respuestas de error (codigos 4xx, 5xx) retornan un objeto error:

    ```json theme={null}
    {
      "error": "ERROR_CODE",
      "message": "Mensaje legible para humanos",
      "details": {
        "campo": "valor"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Códigos HTTP

pan API usa códigos HTTP estandar:

| Código | Significado           | Descripción                          |
| ------ | --------------------- | ------------------------------------ |
| 200    | OK                    | Request exitoso                      |
| 201    | Created               | Recurso creado                       |
| 400    | Bad Request           | Request inválido                     |
| 401    | Unauthorized          | API key faltante o inválida          |
| 403    | Forbidden             | Límite de recursos excedido          |
| 404    | Not Found             | Recurso no existe                    |
| 429    | Too Many Requests     | Rate limit excedido                  |
| 500    | Internal Server Error | Error del servidor                   |
| 503    | Service Unavailable   | Servicio temporalmente no disponible |

## Resumen de Endpoints

### Wallets

| Método | Endpoint              | Descripción               |
| ------ | --------------------- | ------------------------- |
| POST   | `/wallets`            | Crear wallet              |
| GET    | `/wallets/:userId`    | Obtener wallet por userId |
| GET    | `/balances/:walletId` | Obtener balances          |

### Intents

| Método | Endpoint             | Descripción              |
| ------ | -------------------- | ------------------------ |
| POST   | `/intents`           | Crear intent             |
| GET    | `/intents/:intentId` | Obtener estado de intent |

### Yields

| Método | Endpoint  | Descripción              |
| ------ | --------- | ------------------------ |
| GET    | `/yields` | Obtener APYs disponibles |

### Demo

| Método | Endpoint     | Descripción              |
| ------ | ------------ | ------------------------ |
| POST   | `/demo/fund` | Fondear wallet de prueba |

## Rate Limits

Los rate limits dependen de tu plan de suscripción:

| Plan       | Requests por minuto | Wallets maximas |
| ---------- | ------------------- | --------------- |
| Free       | 100                 | 100             |
| Pro        | 1,000               | 10,000          |
| Enterprise | Custom              | Ilimitadas      |

Cuando excedes el rate limit, recibiras un `429 Too Many Requests`:

```
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248000
```

## Créditos

Cada request consume créditos de tu cuenta:

| Endpoint          | Créditos |
| ----------------- | -------- |
| POST /wallets     | 1        |
| GET /wallets/:id  | 1        |
| GET /balances/:id | 1        |
| GET /yields       | 1        |
| POST /intents     | 5        |
| GET /intents/:id  | 1        |

## SDKs Oficiales

<CardGroup cols={2}>
  <Card title="SDK JavaScript/TypeScript" icon="js" href="/sdk/instalacion">
    SDK oficial con soporte TypeScript completo
  </Card>

  <Card title="Python SDK" icon="python" href="https://github.com/pan-dev/pan-python">
    SDK oficial con soporte async
  </Card>
</CardGroup>

<Info>
  Los SDKs son opcionales. Puedes usar cualquier cliente HTTP para interactuar con pan API. Todos los endpoints son REST estandar.
</Info>

## Soporte

<Card title="Email" icon="envelope">
  [support@pan.tech](mailto:support@pan.tech)
</Card>