Onboarding: rails, use cases and interaction

This guide is for eSIM businesses that already sell — operators, MVNOs, resellers, travel platforms — and want AI agents as customers: what the AIMarket rails are, what connecting gives you, how the parts talk, and the four ways in, keeping your own platform.

Other documents: overview · integrations · SDK reference · operator guide · agent guide

1. What the rails are

AIMarket is a federation of hubs where AI agents find capabilities and pay for them. Three mechanisms make it work, and the kit uses all three:

The hub routes discovery, never money. It does not hold funds, does not see the activation code, and takes no fee on direct sales.

flowchart LR
  subgraph discovery["Discovery (hub)"]
    M["Your manifest<br/>signed by your node key"] --> ADM["Admission check<br/>esim.quote with a real country"]
    ADM --> L["Listed: esim.quote@v1, esim.status@v1"]
    L --> S["market_search by agents<br/>on any hub of the federation"]
  end
  subgraph trade["Trade (direct)"]
    Q["quote — free, signed"] --> O["order — 402, x402 USDC"]
    O --> D["delivery — activation code"]
    D --> ST["status — free, token-bound"]
  end
  S --> Q

2. Why connect

• A new sales channel that does not need you to sell to it. Agents compare offers by price, data and coverage across every seller. A good price is found without marketing.
• No integration per agent platform. One contract, esim.*@v1, is what every agent uses with every seller.
• Money without a processor. USDC on Base lands in your wallet when the eSIM is delivered. No chargebacks: a payment settles only after delivery, and a failed settlement cancels the eSIM.
• Your systems stay yours. The kit calls your supplier or provisioning system through five endpoints and tells your CRM and billing about every sale through signed webhooks.
• The same offers for people. The optional storefront sells the same catalogue at the same margin, in five languages, for ten payment networks.

3. Use cases

3.1 A travel agent books a trip and adds data

sequenceDiagram
  participant U as Traveller
  participant Ag as Travel agent (AI)
  participant Hub as AIMarket hub
  participant N as Seller node
  U->>Ag: "Tokyo, 12 days, I need data"
  Ag->>Hub: market_search "eSIM Japan"
  Hub-->>Ag: sellers with esim.quote@v1
  Ag->>N: quote {country: JP, min_gb: 5, min_days: 12}
  N-->>Ag: 3 offers, signed
  Ag->>U: "5 GB, 15 days, $6.40 — buy?"
  U->>Ag: yes
  Ag->>N: order + x402 USDC
  N-->>Ag: activation code, QR, install link
  Ag->>U: QR code and install steps

3.2 An existing reseller adds the agent channel

You already sell eSIMs on your own site, from your own supply. You run the kit with SUPPLIER=http and implement five endpoints in your platform. Your storefront stays as it is; the kit's own storefront can stay off. Every agent sale arrives in your systems as an agent_order.delivered webhook and in your wallet as USDC.

3.3 An MVNO or telecom exposes its own profiles

Your SM-DP+ or provisioning API makes the profiles. The HTTP supplier's POST /orders reserves one, GET /profiles returns its activation code when it is ready, and cancel returns an unused one to stock. The kit adds the x402 checkout, the signatures and the federation.

3.4 A corporate travel or expense assistant

An assistant that books trips for employees buys an eSIM per trip, keeps esim_tran_no and status_token, and checks esim.status before the employee flies back: data used, days left. Finance reconciles each USDC payment against the webhook events.

3.5 A super-app or a Telegram mini-app

A wallet-first app (TON, Telegram) calls the seller node from its backend: quote, then order with x402, or sends its users to the storefront that takes USDT on TON. The same node serves both.

3.6 A new operator with nothing but a wholesale account

An eSIM Access account, a server and a domain: docker compose up gives the agent node, the federation node and the storefront. This is how esim-shop.modelmarket.dev runs, in demo mode.

4. The four ways in

flowchart TB
  subgraph A["A · whole kit"]
    A1["Caddy"] --> A2["store"] & A3["rails"] & A4["node"]
    A2 & A3 --> A5["eSIM Access"]
  end
  subgraph B["B · HTTP supplier"]
    B1["Caddy"] --> B2["store (optional)"] & B3["rails"] & B4["node"]
    B2 & B3 -->|"signed HTTP"| B5["Your system<br/>/catalog /orders /profiles /balance"]
  end
  subgraph C["C · SDK"]
    C1["Your service"] --> C2["createNode()"]
    C2 --> C3["your supplier object"]
  end
  subgraph D["D · contract"]
    D1["Your agent API<br/>any language"] --> D2["esim-rails check"]
  end

Every path then announces to a hub the same way (see the operator guide, section 9): write node.toml, start aimarket node, run aimarket doctor, then aimarket node knock.

5. How the parts talk

5.1 An agent's order, end to end

sequenceDiagram
  autonumber
  participant Ag as Agent
  participant N as Seller node
  participant F as x402 facilitator
  participant S as Supplier
  participant CRM as Your systems
  Ag->>N: POST /order {offer_id}
  N-->>Ag: 402 + PAYMENT-REQUIRED (exact, USDC, eip155:8453, price, payTo)
  Ag->>N: POST /order + PAYMENT-SIGNATURE
  N->>F: verify the authorization
  N->>S: order {transaction_id = hash(payer, nonce), plan, cost}
  S-->>N: order_ref
  loop until the profile is ready (≤ 45 s)
    N->>S: profiles {order_ref}
  end
  N->>F: settle
  F-->>N: settled (USDC moved to your wallet)
  N-->>Ag: 200 delivery
  N-)CRM: agent_order.delivered (signed webhook)

If the profile is not ready in 45 seconds, the agent gets 503 allocation_pending and nothing is settled; the same payment sent again finds the same order. If settlement fails, the node cancels the profile and sends agent_order.cancelled.

5.2 A storefront order

stateDiagram-v2
  [*] --> awaiting_payment: order made (price held 20 min)
  awaiting_payment --> delivered: payment found, eSIM bought
  awaiting_payment --> refund_due: paid, supplier refused
  awaiting_payment --> underpaid: less than the price
  awaiting_payment --> expired: nothing in 24 h
  delivered --> [*]
  refund_due --> [*]: you refund
  underpaid --> [*]: you refund or complete
  expired --> [*]

Each change of status is an order.<status> webhook to your systems.

5.3 Where the money goes

flowchart LR
  P["Traveller"] -->|"USDT · USDC · TON<br/>10 networks"| W["Your wallets"]
  AG["Agent"] -->|"USDC on Base, x402"| W
  W -->|"you top up"| SUP["Your supplier balance"]
  SUP -->|"cost per eSIM"| K["profiles"]
  HUB["AIMarket hub"] -.->|"no money, no fee"| W

5.4 Who sees what

6. Connecting your systems

The SDK reference has every endpoint, payload and signature, with code.

7. Onboarding checklist for an existing operator

1. Read the agent guide to see what agents will call.
2. Choose a path (section 4). For B, implement the five endpoints; rails/examples/operator-backend.mjs is a reference.
3. Run the kit with DEMO_MODE=1 and your supplier; check that the catalogue loads (/agents/healthz).
4. Point WEBHOOK_URL at a test endpoint of your CRM; make one test order (operator guide, section 10).
5. Run esim-rails check https://<your domain>/agents --country <a country you sell> until every line is ✓.
6. Start the federation node and knock on a hub. Search for yourself with market_search.
7. Set DEMO_MODE=0. You are selling to agents.

8. Questions

Do hubs take a fee? Not on direct sales: the agent pays your node over x402.

Can I keep my own storefront and prices? Yes. Path B or C, with the kit's storefront off, or on with your margin.

Which agents can buy? Any client that speaks x402 v2 with USDC on Base, and any MCP client connected to an AIMarket hub for discovery.

What if the hub is down? Your node keeps selling to agents that know its URL; discovery returns when the hub does.

Can I sell day passes or top-ups? Not in v1: esim.*@v1 sells fixed plans of a set size and duration.

Do I need a company? You are the merchant: your terms, your refunds, your taxes. See the operator guide, section 13.