← 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 virtual cards and buy eSIM or gift cards with prepaid USDT.

Register an Ed25519 key, fund USDT on TRC-20, then buy the live catalog (virtual cards, eSIM, gift cards). New agents start at tier 0: catalog spend only — no withdraw, no C2C, no convert. This is not the company B2B API and not a human Wallet login.

Facts

WhoAutonomous agents. Identity-only register. No KYB WaaS, no child wallets.
AuthPOST /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).
MoneyLedger 2401 USDT of that client_id. Register does not credit 2401.
DepositUSDT 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.
BuyRetail URLs: /api/pin/create_card, topup_card, /api/purchase, /api/esim/*. ext_id required. payment_source=stars → 403.
TiersTier 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 and C2C stay closed. The agent cannot self-promote. Full policy: agent tiers.
KYTPaid address screen: /api/kyt_quote, kyt_check. Debits 2401. You get a report; deposit credits on network confirmations. IMBA turns the channel on.
ForbiddenWithdraw, C2C (as payer or payee), 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).
HMACIMBA 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.
OTPNever 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 unavailableCaution 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.
Machine docsapi-docs Agent API · OpenAPI · well-known · llms-agent.txt · llms.txt

Where it is useful

A prepaid agent pays for catalog goods — not for turning IMBA into an anonymous mixer.

Issue a cardFund 2401, then create_card / top-up from USDT.
Travel eSIMBuy a data plan from the same prepaid balance.
Gift catalogBrand codes after the order completes. Not Stars.

Deposit rules (must)

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

Read also

Agent tiers 0 / 1+AML: convert closed at 0; at 1 by request. B2B APICompany KYB, ledger 2403, /api/partner. TRC-20 USDT depositHuman HowTo for Tron USDT (agents: refetch always). Convert (humans)Agents: closed at tier 0; tier 1 by request. C2C by emailHuman rail. Agents cannot send or receive C2C. FAQCards, USDT, and Agent API questions.

FAQ

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?

No. Withdraw and C2C are closed. The live default is catalog spend 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 and C2C stay closed. 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.