Agentcard — the owner’s card as a rail

Agentcard stores a person’s card and shops on their behalf through one conversational purchase API: ask for something, get a cart with a fixed price, confirm the cart. Regent sits in the gap between ask and confirm. The agent may ask freely; it may confirm only after the gate has decided, on the merchant’s total, under the owner’s budget.

Regent never holds the card. The owner stores it with Agentcard (passkey); Regent keeps the Agentcard user id and the card’s brand and last four digits, nothing more.

Supported shops come from Agentcard: Amazon, Walmart, Target, Best Buy and others in the retail set, plus delivery services the owner has linked there. Carts are priced in USD.

Link the card

Open Connect → Gateway in the console

The Your card, through Agentcard panel. An admin of the organization clicks Link my card.

Store the card at Agentcard

A link opens Agentcard’s own page. The owner stores the card there with a passkey and comes back. The console checks every few seconds; the link is good for 24 hours.

Two tools appear

The moment Agentcard reports the card, the organization’s catalog gets agentcard_shop and agentcard_buy, bound to that owner’s Agentcard user. Nothing to vault: Regent is Agentcard’s client and exchanges its own credential for the hour-long token the gateway calls with.

The panel shows a sandbox card or live card badge: Agentcard’s credential decides which, not the organization. A sandbox organization cannot link a live card — the console refuses with AGENTCARD_LIVE_IN_SANDBOX; go live first. A live card linked earlier into an organization that is still a sandbox is flagged in red.

Every time the panel loads, Regent asks Agentcard whether the card is still there. When it is not (removed at Agentcard, or the connection changed), the link turns detached and both tools are taken away, so the agent is never offered a rail that would fail. Link again to continue.

The agent needs a USD budget

The two tools are priced in USD. An agent whose mandate is in another currency is refused with MANDATE_NOT_FOUND and a hint naming USD; a connector agent can then ask the owner for one with request_budget (Tools MCP), or the owner creates a USD mandate under Mandates. Keep ask first on: Agentcard purchases are exactly the case where a person should see the cart before money moves.

The two tools

Tool	What it does	Mandate	Can confirm?
`agentcard_shop`	`POST /buy` with an ask: Agentcard shops and returns a cart with a `hash`, the items, an estimate and a ceiling	no	never — `confirm` and `payment_source` are refused in its body
`agentcard_buy`	`POST /buy` with confirm (the cart hash) and the `conversation_id`: places the order on the owner’s card	yes, in USD	yes, after the gate decides

The owner’s Agentcard user_id is forced into every call by the gateway; an agent cannot name another person. Both tools are ordinary gateway tools over MCP (see Tools MCP): method, path and body.

Ask → decide → confirm

1. Ask. No money is involved; the gate still logs the call.

{
  "name": "agentcard_shop",
  "arguments": {
    "method": "POST", "path": "buy",
    "body": { "ask": "one pack of AA batteries from Amazon, cheapest" }
  }
}

Agentcard answers with a conversation_id and one or more carts. The fields that matter:

{
  "conversation_id": "conv_…",
  "carts": [{
    "hash": "808ca6d4a387c27f",
    "store": { "id": "amazon", "name": "Amazon" },
    "merchant": "retail",
    "currency": "usd",
    "totalCents": 999,
    "totalIsEstimate": true,
    "approvedCeilingCents": 2099,
    "items": [ … ]
  }]
}

Agentcard may ask for a delivery address, phone and name before it can price a cart; the agent answers in the same conversation with further ask turns.

2. Decide. When the agent confirms, the gateway does not trust the amount in the agent’s call. It reads the conversation from Agentcard (GET /buy/conversations/{id}), finds the cart whose hash matches the confirm value, and takes its price:

approvedCeilingCents when totalIsEstimate is true — the person approves the worst case; tax, shipping and fees land at checkout and the final charge can only be lower;
totalCents when the price is final.

That amount, in USD, is what the gate decides on: per-transaction limit, monthly budget, the daily cap for this seller, the ask-first threshold, Guardian. The payee is the cart’s store.id (amazon, walmart, …), read from Agentcard, never from the agent — so caps per seller written as amazon=… apply here. A confirm whose hash is not on the conversation, or that spans two different stores, is refused with AMOUNT_UNRESOLVED; a cart with no store is refused with PAYEE_UNRESOLVED. Fail closed.

3. Confirm. Only after an allow:

{
  "name": "agentcard_buy",
  "arguments": {
    "method": "POST", "path": "buy",
    "body": { "conversation_id": "conv_…", "confirm": "808ca6d4a387c27f" },
    "idempotency_key": "batteries-2026-10-18",
    "intent": "AA batteries for the office"
  }
}

The gateway adds payment_source: "vault" and the owner’s user_id, and forwards the call. Agentcard answers with status (order_placed, declined, needs_input), an order_id and, when the owner must approve on their device, an approval_url.

⚠️

Two approvals, two places. Regent’s ask first parks the decision (ESCALATION_REQUIRED) until the owner signs it in the console; the agent then repeats the call with the same idempotency_key. Agentcard’s own device approval (approval_url) is separate and comes after — it protects the card, Regent’s protects the budget. Set Agentcard’s auto-approval window if the owner wants to approve once, in Regent.

Settlement and receipts

The gate holds the ceiling as a reservation when it allows the confirm. The reservation is settled by Agentcard’s order.placed webhook (settlement reference agentcard:<conversation_id>), and the budget counter moves to what was actually charged, not the ceiling. When Agentcard places nothing — declined, or needs_input with no order and no approval pending — the hold is released at once.

Every confirm produces a signed decision receipt like any other gateway payment: amount, currency, payee (amazon), the mandate version, the policy and the approval, verifiable offline with the receipt verifiers. The delivery address and the card never appear in it.

What Regent sees and what it does not

Regent records	Regent never holds
the Agentcard user id, card brand and last four digits	the card number, expiry or CVV
the conversation id, the cart hash, the store and the decided amount	the owner’s Agentcard passkey
the decision, the approval and the settlement	the money — the charge is Agentcard’s, on the owner’s card

Delivery details given in the conversation pass through the gateway to Agentcard like any tool body; they are not part of the receipt.

Sandbox

With Agentcard’s sandbox credential the purchase API prices real carts but places no orders: a confirm returns needs_input with decline_code: sandbox_mode, Regent releases the hold, and nothing is charged. It is the right place to rehearse the whole loop — ask, decision, approval, retry — before the owner links a live card in a live organization.

Unlink

Unlink in the console removes the two tools and forgets the user id. The card stays with Agentcard, where the owner manages it.

Tool Catalog Introduction