IMBA Partner API

Quick start

Every request goes to https://api.imba.live/v1/partner over HTTPS and returns JSON. All prices are in US dollars.

1. Ask us for a key. It is shown once, so keep it in your server config, never in a browser or app.
2. Top up your balance with crypto (details).
3. Read the catalog, pick a sku, and place the order.

curl https://api.imba.live/v1/partner/me \
  -H "Authorization: Bearer imba_live_xxxxxxxx"

{
  "name": "TravelBot",
  "status": "active",
  "balance_usd": 42.5,
  "limits": { "requests_per_minute": 60, "daily_spend_usd": 200.0, "spent_today_usd": 3.4 }
}

Authentication

Send the key as a bearer token: Authorization: Bearer <key>. The header X-API-Key: <key> works as well. A missing or wrong key returns 401; a suspended key returns 403.

Call the API from your server. If a key leaks, we replace it and the old one stops working at once.

eSIM catalog

Every country we cover, with the number of packages and the lowest price:

{
  "currency": "USD",
  "countries": [
    { "code": "DE", "name": "Germany", "packages": 24, "from_price_usd": 0.72 },
    { "code": "TH", "name": "Thailand", "packages": 40, "from_price_usd": 0.68 }
  ]
}

The packages for one country (ISO 3166-1 alpha-2 code). The sku is what you pass when ordering.

{
  "currency": "USD",
  "country": "TH",
  "name": "Thailand",
  "packages": [
    { "sku": "PQ2I5PFIT", "name": "Thailand 100MB 7Days", "data_gb": 0.1,
      "duration_days": 7, "speed": "3G/4G/5G", "price_usd": 0.68 }
  ]
}

The catalog is refreshed from our suppliers every 30 minutes and answers in milliseconds, so you can read it on every page view. Prices can change between refreshes: the price you are charged is the one in the order response.

VPN catalog

{
  "currency": "USD",
  "plans": [
    { "months": 1, "price_usd": 2.99 },
    { "months": 3, "price_usd": 7.49 },
    { "months": 6, "price_usd": 13.49 },
    { "months": 12, "price_usd": 19.99 }
  ]
}

Buy an eSIM

Body: sku (required) and label (optional note, up to 100 characters). Send an Idempotency-Key header (why).

curl -X POST https://api.imba.live/v1/partner/orders/esim \
  -H "Authorization: Bearer imba_live_xxxxxxxx" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{"sku": "PQ2I5PFIT", "label": "Anna, Bangkok trip"}'

{
  "order_id": "a5f0b74b-b1b2-44a0-90f4-490e6477adfa",
  "kind": "esim",
  "sku": "PQ2I5PFIT",
  "country": "TH",
  "data_gb": 0.1,
  "duration_days": 7,
  "iccid": "8910300000012345678",
  "activation_code": "LPA:1$smdp.example.com$ABCD-1234",
  "qr_code": "https://.../qr.png",
  "charged_usd": 0.68,
  "balance_usd": 41.82
}

Show the customer the qr_code image, or give them the activation_code to type in under Settings, Cellular, Add eSIM. If the supplier fails, you are not charged.

Buy or extend VPN

Body: months (one of the plans in the VPN catalog). Add key_id to extend a key you bought earlier instead of issuing a new one.

curl -X POST https://api.imba.live/v1/partner/orders/vpn \
  -H "Authorization: Bearer imba_live_xxxxxxxx" \
  -H "Idempotency-Key: vpn-2042" \
  -H "Content-Type: application/json" \
  -d '{"months": 3}'

{
  "order_id": "9d1c2f3e-1b2a-4c5d-8e9f-0a1b2c3d4e5f",
  "kind": "vpn",
  "key_id": "7e0ec2f7-0cf4-48e9-875c-64ab77f587b7",
  "subscription_url": "https://vpn.imba.live/4aW06QUhcCV8pPHA",
  "months": 3,
  "expires_at": "2027-02-06T19:23:42+00:00",
  "charged_usd": 7.49,
  "balance_usd": 34.33
}

subscription_url is a standard subscription link. It opens in Happ, V2Box and other clients that import VLESS subscriptions, and lists every server we run. Keep the key_idto extend the key later.

Order history

Your latest orders (up to 200) and a single order, in the same shape the purchase returned, plus created_at.

Balance and top-up

Returns balance_usd and your limits.

Creates a crypto invoice (paid in cryptocurrency through Heleket). Body: amount_usd, from 5 to 5000. Send the customer or your accountant to payment_url; the balance is credited automatically after the network confirms the payment.

curl -X POST https://api.imba.live/v1/partner/topup \
  -H "Authorization: Bearer imba_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 100}'

{ "payment_id": "heleket_7a19aeb9-cd74-4c62-91a9-5fbdd7641e33",
  "payment_url": "https://pay.heleket.com/pay/...", "amount_usd": 100.0 }

Your latest top-ups with their status (pending, confirmed, expired).

Idempotency

Orders move money, and networks drop connections. Every purchase needs an Idempotency-Key header (8 to 80 characters, for example your own order number). If you repeat a request with the same key, we return the original result with "idempotent_replay": true and do not charge again. Use a new key for a new purchase. Reusing a key for a different kind of order returns 409.

Errors and limits

Errors return a JSON body {"detail": "..."} and an HTTP status:

New keys start at 60 requests per minute and a daily spend limit of $200. Both are shown in GET /me and can be raised on request.