# Nyongeza za salio kwa crypto

> API ya AfricaProxies: kuongeza salio kwa crypto, kiasi halisi, malipo kutumwa (TXID si lazima) na hali. Vigezo, majibu, curl, Python na Node.js.

- URL: https://africaproxies.com/sw/docs/api/top-ups/
- Iliyoruushwa mwisho: 2026-10-15
- Mchapishi: AfricaProxies (https://africaproxies.com)

Ongeza salio kwa crypto: pata anwani ya kupokea na kiasi halisi, tuma kiasi hicho kamili, ripoti malipo kuwa yametumwa (ID ya muamala si lazima), kisha fuatilia nyongeza hadi salio liwekwe. Salio linalipia mpango wetu wowote.

**Vituo vya maombi kwenye ukurasa huu**

- `GET /v1/catalog/coins`: Sarafu za crypto na mitandao inayokubaliwa (pamoja na anwani zake za kupokea zisizobadilika)
- `POST /v1/topups`: Anzisha nyongeza ya salio kwa crypto (anwani ileile, kiasi halisi)
- `POST /v1/topups/{topUpId}/txid`: Ripoti malipo kuwa yametumwa (TXID si lazima)
- `GET /v1/topups/{topUpId}`: Pata nyongeza ya salio (uliza hali yake ya sasa)
- `GET /v1/topups`: Orodhesha nyongeza za salio kwa crypto

URL ya msingi `https://africaproxies.com/api/v1`. Uthibitishaji, hitilafu na vikomo: angalia [muhtasari wa API](/sw/docs/api/).

## Sarafu za crypto na mitandao inayokubaliwa (pamoja na anwani zake za kupokea zisizobadilika)

`GET /v1/catalog/coins`

Umma: hakuna API inahitajika.

**Jibu** `200 OK`

```json
{
  "data": [
    {
      "code": "BTC",
      "name": "Bitcoin",
      "networks": [
        {
          "id": "bitcoin",
          "name": "Bitcoin",
          "confirmationsRequired": 2,
          "estimatedMinutes": null,
          "memoRequired": false,
          "address": "DEPOSIT_ADDRESS"
        }
      ]
    }
  ]
}
```

*curl*

```bash
curl -s "https://africaproxies.com/api/v1/catalog/coins"
```

*Python*

```python
import os
import requests

API = "https://africaproxies.com/api/v1"

r = requests.get(f"{API}/catalog/coins", timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://africaproxies.com/api/v1';

const res = await fetch(`${API}/catalog/coins`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Anzisha nyongeza ya salio kwa crypto (anwani ileile, kiasi halisi)

`POST /v1/topups`

- `amountUsd` ≥ 25.00 USD na ≤ kiwango cha juu (10,000.00 kwa chaguo-msingi): vinginevyo `422` kwenye `amountUsd`.
- `coin` + `network` lazima viwe katika `GET /v1/catalog/coins` (vinginevyo `409 coin_unavailable`).
- Inarudisha `address` **isiyobadilika** ya mtandao na kiasi halisi `amountCrypto` = `amountUsd` / `rate` kilichozungushwa **kwenda juu** kulingana na usahihi wa sarafu (BTC/LTC/ETH/SOL nafasi 8 za desimali, USDT/USDC nafasi 6), pamoja na tofauti ndogo ya kipekee katika tarakimu za mwisho ili nyongeza mbili zilizo wazi kwenye mtandao uleule zisiombe kiasi sawa. `rate` inafungwa hadi `expiresAt` (dakika 30); `txidDeadline` = `expiresAt` + saa 72.
- `purchase` si lazima (mwili sawa na `POST /v1/orders`): inathibitishwa na kupewa bei sasa (`422` yenye majina ya sehemu yanayoanza kwa `purchase.`, `409 plan_unavailable`…). `amountUsd` lazima itoshe jumla ya `purchase` ukitoa salio la sasa (`422 too_small` kwenye `amountUsd`). Salio likiongezwa, agizo linalipwa kutoka salioni katika muamala uleule; `purchase.status` inakuwa `completed` (yenye `orderId`) au `failed` (`failureReason`; fedha zinabaki kwenye salio).

Uthibitishaji: funguo ya API kwenye kichwa cha `Authorization: Bearer API_KEY`.

**Parameta**

| Jina | Katika | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Hapana | Ufunguo wa kipekee (kwa mfano UUID) wa kurudia POST salama. Huhifadhiwa saa 24. — herufi zisizozidi 128 |

**Mwili wa ombi**

| Uwanja | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- |
| `amountUsd` | string (USD, 2 decimals) | Ndiyo | USD za kuongeza: ≥ 25.00, ≤ 10,000.00 kwa chaguo-msingi. |
| `coin` | string | Ndiyo | — |
| `network` | string | Ndiyo | — |
| `purchase` | object | Hapana | Mpango wa kununua kwa salio nyongeza ikiwekwa (mwili sawa na `POST /v1/orders`). |

*Mfano: Salio*

```json
{
  "amountUsd": "50.00",
  "coin": "USDT",
  "network": "tron"
}
```

*Mfano: Malipo*

```json
{
  "amountUsd": "25.00",
  "coin": "BTC",
  "network": "bitcoin",
  "purchase": {
    "planId": "res-10",
    "quantity": 1
  }
}
```

**Jibu** `201 Created`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "5.94",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://africaproxies.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amountUsd":"50.00","coin":"USDT","network":"tron"}'
```

*Python*

```python
import os, uuid
import requests

API = "https://africaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/topups", headers=HEADERS, json={"amountUsd": "50.00", "coin": "USDT", "network": "tron"}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://africaproxies.com/api/v1';

const res = await fetch(`${API}/topups`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ amountUsd: '50.00', coin: 'USDT', network: 'tron' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Ripoti malipo kuwa yametumwa (TXID si lazima)

`POST /v1/topups/{topUpId}/txid`

Ripoti malipo kuwa yametumwa mara yanapoondoka kwenye pochi yako au soko la kubadilishana: hili ni toleo la API la kitufe cha “Nimetuma malipo”. ID ya muamala (TXID) si lazima: tuma mwili tupu (`{}`), au ongeza `txid` ukiwa nayo. Malipo yanalinganishwa na nyongeza hii kwa kiasi chake halisi (`amountCrypto`) kwenye mtandao na anwani ya nyongeza, hivyo tuma kiasi hicho kamili.

Inakubaliwa nyongeza ikiwa `awaiting_payment`, `expired` au `rejected`, na kabla ya `txidDeadline` (`expiresAt` + saa 72): kuripoti kuchelewa hakupotezi malipo. `txid` ikitolewa, inakaguliwa kulingana na muundo wa mtandao (`422` kwenye `txid`), na haitakiwi kutumiwa na nyongeza nyingine (`409 txid_already_used`). Nyongeza iliyofungwa inarudisha `409 topup_closed`. Kisha nyongeza inakuwa `verifying` wakati malipo yanakaguliwa kwenye blockchain, na inaishia `credited` mtandao unapothibitisha muamala, au `rejected` (pamoja na `rejection`).

Uthibitishaji: funguo ya API kwenye kichwa cha `Authorization: Bearer API_KEY`.

**Parameta**

| Jina | Katika | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- | --- |
| `topUpId` | path | string | Ndiyo | — |

**Mwili wa ombi**

| Uwanja | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- |
| `txid` | string | Hapana | Si lazima. Hashi ya muamala: herufi za hex 64 (bitcoin, litecoin, tron), 0x + herufi za hex 64 (ethereum), saini ya base58 (solana). Tupu au haipo: malipo yanalinganishwa kwa kiasi chake halisi. — herufi zisizozidi 128 |

*Mfano: Malipo yametumwa*

```json
{}
```

*Mfano: Kwa TXID (si lazima)*

```json
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
}
```

**Jibu** `200 OK`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "5.94",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://africaproxies.com/api/v1/topups/top_7d2kq9x1/txid" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

*Python*

```python
import os
import requests

API = "https://africaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.post(f"{API}/topups/top_7d2kq9x1/txid", headers=HEADERS, json={}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://africaproxies.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1/txid`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Pata nyongeza ya salio (uliza hali yake ya sasa)

`GET /v1/topups/{topUpId}`

Uliza njia hii kufuatilia nyongeza: kila sekunde 10 ikiwa `status = verifying`, kila sekunde 30 ikisubiri malipo, na acha ikiwa `final = true`. Nyongeza inakuwa `expired` malipo yasiporipotiwa kuwa yametumwa kabla ya `expiresAt`; bado yanaweza kuripotiwa hadi `txidDeadline`.

Uthibitishaji: funguo ya API kwenye kichwa cha `Authorization: Bearer API_KEY`.

**Parameta**

| Jina | Katika | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- | --- |
| `topUpId` | path | string | Ndiyo | — |

**Jibu** `200 OK`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "5.94",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s "https://africaproxies.com/api/v1/topups/top_7d2kq9x1" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://africaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups/top_7d2kq9x1", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://africaproxies.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Orodhesha nyongeza za salio kwa crypto

`GET /v1/topups`

Uthibitishaji: funguo ya API kwenye kichwa cha `Authorization: Bearer API_KEY`.

**Parameta**

| Jina | Katika | Aina | Inahitajika | Maelezo |
| --- | --- | --- | --- | --- |
| `page` | query | integer | Hapana | ≥ 1, chaguo-msingi `1` |
| `perPage` | query | integer | Hapana | 1–100, chaguo-msingi `20` |
| `status` | query | `awaiting_payment` · `verifying` · `credited` · `rejected` · `expired` | Hapana | `final` = imeongezwa kwenye salio, au imeisha muda/imekataliwa baada ya `txidDeadline`. |

**Jibu** `200 OK`

```json
{
  "data": [
    {
      "id": "top_7d2kq9x1",
      "status": "verifying",
      "final": false,
      "amountUsd": "25.00",
      "coin": "USDT",
      "network": "tron",
      "address": "DEPOSIT_ADDRESS",
      "amountCrypto": "25.000137",
      "rate": "1.00",
      "paymentUri": "PAYMENT_URI",
      "expiresAt": "2026-10-05T14:33:11Z",
      "txidDeadline": "2026-10-08T14:33:11Z",
      "confirmationsRequired": 20,
      "confirmations": 7,
      "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "txidSubmittedAt": "2026-10-05T14:09:42Z",
      "amountReceivedCrypto": "25.000137",
      "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "creditedUsd": null,
      "creditedAt": null,
      "rejection": null,
      "purchase": {
        "planId": "res-10",
        "planName": "Team",
        "quantity": 1,
        "options": {},
        "promoCode": null,
        "total": "5.94",
        "status": "pending",
        "orderId": null,
        "failureReason": null
      },
      "createdAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

*curl*

```bash
curl -s "https://africaproxies.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://africaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://africaproxies.com/api/v1';

const res = await fetch(`${API}/topups`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

---

AfricaProxies: AfricaProxies ni mtoa huduma za proxy za IP za nyumbani kwa Afrika kusini mwa Sahara, zinazolipiwa kwa kripto bila kupakia kitambulisho.