API reference

Crypto top-ups

Top up the balance in crypto: get the deposit address and the unique exact amount, send it, mark the top-up as sent, then follow the confirmations until the balance is credited. Payments are matched automatically by their exact amount. The balance buys any product in any country.

Last updated: October 6, 2026 · 7 min read

Endpoints on this page

GET /v1/catalog/coins: Accepted cryptocurrencies and networks (with their fixed deposit address)
POST /v1/topups: Start a crypto top-up of the balance (fixed address, exact amount)
POST /v1/topups/{topUpId}/txid: Declare the transaction id (TXID) of the payment
GET /v1/topups/{topUpId}: Get a top-up (poll for its live status)
GET /v1/topups: List crypto top-ups

Base URL https://statesideip.com/api/v1. Authentication, errors and limits: see the API overview.

Accepted cryptocurrencies and networks (with their fixed deposit address)

GET/v1/catalog/coins

Public: no API key needed.

Response `200 OK`

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

Code examples

curl

curl -s "https://statesideip.com/api/v1/catalog/coins"

Python

import os
import requests

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

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

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://statesideip.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());

Start a crypto top-up of the balance (fixed address, exact amount)

POST/v1/topups

amountUsd ≥ 25.00 USD and ≤ the maximum (10,000.00 by default): 422 on amountUsd otherwise.
coin + network must be one of GET /v1/catalog/coins (409 coin_unavailable otherwise).
Returns the network's fixed address and the exact amountCrypto = amountUsd / rate rounded up to the coin's precision (BTC/LTC/ETH/SOL 8 decimals, USDT/USDC 6), plus a small unique offset in the last digits so that no two open top-ups of the same network ask for the same amount. rate is locked until expiresAt (30 minutes); txidDeadline = expiresAt + 72 h.
Optional purchase (same body as POST /v1/orders): validated and priced now (422 with field names prefixed by purchase., 409 plan_unavailable…). amountUsd must cover purchase total − current balance (422 too_small on amountUsd). When the top-up is credited the order is placed from the balance in the same transaction; purchase.status becomes completed (with orderId) or failed (failureReason; the funds stay on the balance).

Authentication: API key in the Authorization: Bearer API_KEY header.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	Unique key (e.g. a UUID) to safely retry a POST. Kept 24 h. — max. 128 characters

Request body

Field	Type	Required	Description
`amountUsd`	string (USD, 2 decimals)	Yes	USD to add: ≥ 25.00, ≤ 10,000.00 by default.
`coin`	string	Yes	—
`network`	string	Yes	—
`purchase`	object	No	Plan to buy automatically once the top-up is credited.

Example: Balance

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

Example: Checkout

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

Response `201 Created`

{
  "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": "Basic",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Code examples

curl

curl -s -X POST "https://statesideip.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

import os, uuid
import requests

API = "https://statesideip.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

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

const res = await fetch(`${API}/topups`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': crypto.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());

Declare the transaction id (TXID) of the payment

POST/v1/topups/{topUpId}/txid

Mark the top-up as sent once the payment has left your wallet or exchange (body may be empty: the payment is matched automatically by its unique exact amount). An optional txid speeds up the match. Accepted while the top-up is awaiting_payment, expired or rejected, and before txidDeadline (expiresAt + 72 h).

If a txid is given, its format is checked for the network (422 on txid) and it must not be claimed by another top-up (409 txid_already_used). A closed top-up returns 409 topup_closed. The top-up is then verifying while the payment is matched on-chain, and ends credited or rejected (with rejection).

Authentication: API key in the Authorization: Bearer API_KEY header.

Parameters

Name	In	Type	Required	Description
`topUpId`	path	string	Yes	—

Request body

Field	Type	Required	Description
`txid`	string	Yes	Transaction hash: 64 hex (bitcoin, litecoin, tron), 0x + 64 hex (ethereum), base58 signature (solana). — max. 128 characters

Example

{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
}

Response `200 OK`

{
  "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": "Basic",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Code examples

curl

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

Python

import os
import requests

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

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

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://statesideip.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({
    txid: '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b',
  }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Get a top-up (poll for its live status)

GET/v1/topups/{topUpId}

Poll this route to follow a top-up: every 10 s while status = verifying, every 30 s while it waits for the payment, and stop when final = true. A top-up becomes expired when no payment of its exact amount arrived before expiresAt; a payment that arrives late is still matched until txidDeadline.

Authentication: API key in the Authorization: Bearer API_KEY header.

Parameters

Name	In	Type	Required	Description
`topUpId`	path	string	Yes	—

Response `200 OK`

{
  "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": "Basic",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Code examples

curl

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

Python

import os
import requests

API = "https://statesideip.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

// Node.js 18+ (built-in fetch), ES module
const API = 'https://statesideip.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());

List crypto top-ups

GET/v1/topups

Authentication: API key in the Authorization: Bearer API_KEY header.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	≥ 1, default `1`
`perPage`	query	integer	No	1–100, default `20`
`status`	query	`awaiting_payment` · `verifying` · `credited` · `rejected` · `expired`	No	`final` = credited, or expired / rejected after `txidDeadline`.

Response `200 OK`

{
  "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": "Basic",
        "quantity": 1,
        "options": {},
        "promoCode": null,
        "total": "7.50",
        "status": "pending",
        "orderId": null,
        "failureReason": null
      },
      "createdAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}

Code examples

curl

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

Python

import os
import requests

API = "https://statesideip.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

// Node.js 18+ (built-in fetch), ES module
const API = 'https://statesideip.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());

Accepted cryptocurrencies and networks (with their fixed deposit address)

Response 200 OK

Code examples

Start a crypto top-up of the balance (fixed address, exact amount)

Parameters

Request body

Response 201 Created

Code examples

Declare the transaction id (TXID) of the payment

Parameters

Request body

Response 200 OK

Code examples

Get a top-up (poll for its live status)

Parameters

Response 200 OK

Code examples

List crypto top-ups

Parameters

Response 200 OK

Code examples

Related pages

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `200 OK`