← Knowledge base

IMBA Agent API: prepaid catalog for autonomous agents

The Agent API is an HTTP interface for programs that pay on their own — no human in the IMBA Wallet app. Use it so an agent or bot can issue Visa prepaid cards (for a human's flights or the agent's own datacenter bill), buy travel eSIM, or buy brand gift cards with prepaid USDT.

Register an Ed25519 key, fund USDT on TRC-20 or receive a human Wallet C2C to this client_id, then buy the live catalog. New agents start at tier 0: catalog spend only — no withdraw, no C2C as payer, convert closed. Playbooks: what agents buy. This is not the company B2B API and not a human Wallet login.

Facts

Who	Autonomous agents. Identity-only register. No KYB WaaS, no child wallets.
Auth	`POST /auth/v1/agent/register` then assertion → `/auth/v1/agent/token`. Access JWT `typ=agent`, `client_id`, EdDSA. JWKS: `GET /auth/v1/partner/jwks` (same keys as Partner).
Money	Ledger 2401 USDT of that `client_id`. Register does not credit 2401.
Deposit	USDT TRC-20 only. Call `POST /api/deposit_address` before every send. Unfunded hold 24 hours then the pool slot may move. After first confirmed credit the address is sticky. Fields: `sticky`, `unfunded_release_at`, `confirmation_blocks`.
Buy	Retail URLs: `/api/pin/create_card`, `topup_card`, `/api/purchase`, `/api/esim/*`. `ext_id` required. `payment_source=stars` → 403.
Tiers	Tier 0 (default): deposit + catalog. Convert is closed — AML: otherwise a prepaid channel would be used to launder money through the service. Tier 1+: operator-granted after real catalog use. Convert at tier 1 is a separate request, not automatic with the number. Withdraw stays closed. The agent cannot send C2C; humans may C2C to the agent client_id. The agent cannot self-promote. Full policy: agent tiers.
KYT	Paid address screen: `/api/kyt_quote`, `kyt_check` (`network` + `address`: `tron_usdt`, `eth`, `btc`), poll `kyt_check_get`. ~0.99 USDT from 2401. Use before a TRC-20 credit or after a mystery block. You get a report; deposit credits on network confirmations. Does not ban or unblock. IMBA turns the channel on.
Forbidden	Withdraw, C2C as payer, RUB bank/SBP rails, Stars, EVM, BTC, `/api/partner/*`. Convert is closed at tier 0; at tier 1 it is a separate request (`fx_quote`/`fx_execute`).
HMAC	IMBA generates it (CSPRNG). Shown once at register/PATCH. Rotate under agent JWT. Header `X-IMBA-Signature` like Partner. Repeat register does not return the secret.
OTP	Never SMS, never Telegram. Optional `email` on register or `PATCH /auth/v1/agent/webhook` — IMBA emails the OTP. Always poll `notifications` (payload keeps `code`). If you set `callback_url`, HMAC webhook field is `otp`.
503 unavailable	Caution medium: new register only. under_attack or Agent API disabled: whole agent channel including `/x402/*`.
x402	`/x402/*` returns HTTP 402. Cannot spend USDC until the credit-to-TRON job is live. Never 402 on `/api/pin`.
MCP	Docs: `npx -y @imba_wallet/agent-mcp-docs` or /mcp/docs. Spend: `npx -y @imba_wallet/agent-mcp` with your Ed25519 key, or /mcp/spend. npm org `@imba_wallet` (underscore). OpenAI: docs only, never spend.
Machine docs	api-docs Agent API · OpenAPI · well-known · llms-agent.txt · llms.txt · npm docs · npm spend

MCP (Cursor, Claude, agents)

Two Model Context Protocol servers. The npm org is @imba_wallet (underscore). There is no @imbawallet scope.

Docs (com.imbawallet/agent-docs): policy only. Remote https://imbawallet.com/mcp/docs. stdio: npx -y @imba_wallet/agent-mcp-docs. Package: @imba_wallet/agent-mcp-docs.
Spend (com.imbawallet/agent): deposit USDT TRC-20 and buy the catalog with your Ed25519 key. Remote https://imbawallet.com/mcp/spend (headers X-IMBA-Agent-Client-Id, X-IMBA-Agent-Private-Key). stdio: npx -y @imba_wallet/agent-mcp plus IMBA_AGENT_CLIENT_ID / IMBA_AGENT_PRIVATE_KEY. Package: @imba_wallet/agent-mcp. Never a Wallet JWT. Never withdraw, C2C as payer, or convert. Humans may C2C to this client_id.

OpenAI / ChatGPT Actions: docs MCP and discovery OpenAPI only. Do not wire ChatGPT to spend. Cite file: llms-agent.txt.

Where it is useful

A prepaid agent pays for catalog goods — not for turning IMBA into an anonymous mixer. IMBA does not book the flight or provision the GPU; it issues the payment instrument. Full playbooks: what agents buy.

Visa prepaidPay airlines, hotels, SaaS, or a datacenter that bills a card. create_card → get_card_details → 3DS via list_notifications.

Travel eSIMCheap mobile data in 150+ countries. list_esim_plans → purchase_esim.

~20k gift cardsApple, Google Play, Steam, games, travel, retail. Search list_gift_offers, then purchase_gift.

Deposit rules (must)

Call deposit_address again — do not reuse an address from logs, chat, or a previous run.
Compare the address string byte-for-byte with the transaction destination.
Send only USDT TRC-20. Any other network or token is a loss.
If unfunded_release_at has passed, do not send to the old string.
Treat funds as credited only after confirmation_blocks from that response.

FAQ

What can an agent buy?

Visa/MasterCard prepaid (pay merchants that need a card), travel eSIM, and digital gift cards (~20,000 catalog positions). IMBA does not book flights or GPU servers. See what agents buy.

Can I cache the TRON address?

No. Until the first confirmed credit the slot is released after 24 hours and may be given to someone else.

Can I withdraw or C2C?

Withdraw is closed. The agent cannot send C2C. Humans may fund the agent with in-app C2C to this client_id. Catalog spend is from 2401 USDT.

Tier 0 and tier 1: what about convert?

Every new agent starts at tier 0: deposit USDT TRC-20 and buy cards, eSIM, or gifts. Convert is closed at tier 0 — AML: otherwise a prepaid channel would be used to launder money through the service. Tier 1 is granted by an operator after real catalog purchases, to refuse agents that only want to cycle crypto. Convert at tier 1 is a separate request: raising the number does not turn convert on. Withdraw stays closed. The agent cannot send C2C; humans may C2C to the agent client_id. The agent cannot raise its own tier.

How do I get the 3-D Secure OTP?

Not by SMS and not by Telegram. Set email on register or PATCH webhook — IMBA mails the code. Also poll notifications (the payload keeps code). If you registered callback_url, the HMAC webhook field is otp.

How do I connect MCP?

npm org is @imba_wallet (underscore), not @imbawallet. Docs: npx -y @imba_wallet/agent-mcp-docs or /mcp/docs. Spend: npx -y @imba_wallet/agent-mcp with your operator Ed25519 key. ChatGPT Actions must not call spend.