# GET /v1/balance

Obtener el saldo

Saldo actual del editor: `available` es el importe que se puede solicitar como pago, `pending` son los ingresos estimados (días que AGIMone aún no ha finalizado; no se pueden pagar hasta que sean finales), `requested` es el importe de las solicitudes de pago abiertas, `paid_total` es el total ya pagado y `min_payout` es el importe mínimo de pago. Todos los importes son cadenas de dinero. Mismas cifras que el campo `balance` de GET /v1/earnings. Requiere el scope `publisher:read` (clave de API o sesión web). Nivel de límite de uso: `read`.

- Scope requerido: `publisher:read`
- Límite de uso: `read` — 120 solicitudes por ventana de 60 s por clave de API o sesión web

## Parámetros

Sin parámetros.

## Respuesta

```
{ available: string; held: string; min_payout: string; paid_total: string; pending: string; requested: string }
```

## Errores

Las rutas con límite de uso devuelven `RateLimit-Limit`, `RateLimit-Remaining` y `RateLimit-Reset` (segundos hasta que termina la ventana); un 429 incluye además `Retry-After`. Los encabezados pueden faltar mientras el limitador no esté disponible temporalmente (en ese caso las solicitudes se dejan pasar).

| Estado | Significado |
|---|---|
| 401 | Clave de API ausente, no válida o revocada. |
| 403 | La clave no tiene el scope requerido, o la operación no está permitida para este actor. |
| 429 | Límite de uso superado; espera los segundos indicados en `Retry-After`. |

## Ejemplos

### cURL

```bash
#!/usr/bin/env bash
# GET /v1/balance: current balance (pending, available, requested, paid_total, min_payout).
# Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE.
set -euo pipefail
BASE="${AGIMONE_API_BASE:-https://app.agimone.com}"
curl -fsS -H "Authorization: Bearer $AGIMONE_API_KEY" "$BASE/v1/balance"
echo
```

### Node.js

```js
// GET /v1/balance: current balance (pending, available, requested, paid_total, min_payout). Node 18+, no dependencies.
// Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE.
const base = process.env.AGIMONE_API_BASE ?? 'https://app.agimone.com';

const res = await fetch(`${base}/v1/balance`, {
  headers: { Authorization: `Bearer ${process.env.AGIMONE_API_KEY}` },
});
if (!res.ok) {
  console.error(`HTTP ${res.status}: ${await res.text()}`);
  process.exit(1);
}
console.log(JSON.stringify(await res.json()));
```

### PHP

```php
<?php
// GET /v1/balance: current balance (pending, available, requested, paid_total, min_payout). PHP 8 with the curl extension, no other dependencies.
// Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE.
$base = getenv('AGIMONE_API_BASE') ?: 'https://app.agimone.com';

$ch = curl_init("$base/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AGIMONE_API_KEY')],
    CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    fwrite(STDERR, "HTTP $status: " . ($body === false ? curl_error($ch) : $body) . "\n");
    exit(1);
}
curl_close($ch);
echo trim($body), "\n";
```

### Python

```python
# GET /v1/balance: current balance (pending, available, requested, paid_total, min_payout). Python 3.8+, standard library only.
# Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE.
import json
import os
import sys
import urllib.error
import urllib.request

base = os.environ.get("AGIMONE_API_BASE", "https://app.agimone.com")
req = urllib.request.Request(
    f"{base}/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['AGIMONE_API_KEY']}"},
)
try:
    with urllib.request.urlopen(req, timeout=15) as res:
        print(json.dumps(json.load(res)))
except urllib.error.HTTPError as e:
    print(f"HTTP {e.code}: {e.read().decode()}", file=sys.stderr)
    sys.exit(1)
```

Documentación HTML: https://agimone.com/es/developers/api/#get-balance
API 2026-10
