> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.imbawallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> JSON, amounts, timestamps, isolation, and versioning rules.

# Conventions

## Hosts and transport

| Role | URL                                                     |
| ---- | ------------------------------------------------------- |
| API  | `https://api.imbawallet.com`                            |
| Auth | `POST https://api.imbawallet.com/auth/v1/partner/token` |
| Docs | `https://api-docs.imbawallet.com`                       |

* HTTPS only (TLS 1.2+)
* `Content-Type: application/json` for bodies
* `Authorization: Bearer <access_token>` on Partner endpoints

## Amounts and time

| Rule                  | Detail                                                                   |
| --------------------- | ------------------------------------------------------------------------ |
| Amounts               | Decimal **strings** (`"12.50"`), never JSON numbers                      |
| Currency (settlement) | `USDT`                                                                   |
| Network               | `TRON` (USDT TRC-20)                                                     |
| Alias                 | Query `asset=USDT_TRC20` may be accepted as synonym for currency+network |
| Timestamps            | UTC RFC 3339 (`2026-07-10T09:15:30.123Z`)                                |

## Identity and correlation

| ID                                                      | Who creates it | Purpose                                         |
| ------------------------------------------------------- | -------------- | ----------------------------------------------- |
| `partner_id`                                            | IMBA (in JWT)  | Your tenant                                     |
| `ext_id`                                                | You            | Idempotency key per create (unique per partner) |
| `request_id`                                            | IMBA           | Support correlation on every response           |
| `card_id` / `esim_id` / `purchase_id` / `withdrawal_id` | IMBA           | Product / money resource ids                    |

There is **no** separate “end-customer id” in the API. Correlate your users with `ext_id`, `card_id`, holder fields, etc. on your side.

## Isolation

* You only see your own funds, documents, cards, eSIMs, and gift purchases
* Another tenant’s resource → `404` (no existence leak)
* Missing scope → `403`
* Wallet end-user tokens are rejected

## Versioning

The Partner API is not versioned as a whole. Breaking changes to a method use a new scope and/or an explicit parameter / `Accept` variant for that method.

## Async pattern

Most money and product creates return **`202`** (or idempotent **`200`/`202`** on replay). Track progress with:

1. Webhooks (terminal statuses)
2. `GET /partner/documents/{ext_id}`
3. Product GET endpoints (`cards`, `esims`, `gift-cards`)