# GET /v1/balance

عرض الرصيد

الرصيد الحالي للناشر: `available` هو المبلغ الذي يمكن طلب دفعه، و`pending` هو الإيراد التقديري (أيام لم يعتمدها AGIMone نهائيًا بعد؛ ولا يمكن دفعه قبل أن يصبح نهائيًا)، و`requested` هو المبلغ ضمن طلبات الدفع المفتوحة، و`paid_total` هو إجمالي ما دفع سابقًا، و`min_payout` هو الحد الأدنى لمبلغ الدفع. جميع المبالغ سلاسل نصية للمال. وهي الأرقام نفسها في الحقل `balance` ضمن استجابة GET /v1/earnings. تتطلب الصلاحية `publisher:read` (مفتاح API أو جلسة ويب). فئة حد المعدل: `read`.

- الصلاحية المطلوبة: `publisher:read`
- حد المعدل: `read` — 120 طلبًا لكل نافذة مدتها 60 ثانية لكل مفتاح API أو جلسة ويب

## المعاملات

لا معاملات.

## الاستجابة

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

## الأخطاء

تعيد المسارات الخاضعة لحد المعدل الترويسات `RateLimit-Limit` و`RateLimit-Remaining` و`RateLimit-Reset` (عدد الثواني حتى انتهاء النافذة)؛ وتحمل الاستجابة 429 أيضًا `Retry-After`. قد تغيب الترويسات أثناء عدم توفر المحدّد مؤقتًا (وتمرّر الطلبات حينئذ).

| الحالة | المعنى |
|---|---|
| 401 | مفتاح API مفقود أو غير صالح أو ملغى. |
| 403 | ينقص المفتاح الصلاحية المطلوبة، أو العملية غير مسموح بها لهذا الطرف. |
| 429 | تم تجاوز حد المعدل؛ انتظر `Retry-After` ثانية. |

## أمثلة

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

وثائق HTML: https://agimone.com/ar/developers/api/#get-balance
API 2026-10
