Wallet SDK

Show your users their Agentcard wallet inside your own product. Your backend mints a wallet link, your page loads one script, and the wallet renders in an overlay (or inline): card attachment, the card list, and the pay sheet all run on Agentcard’s surface inside an iframe. Card numbers never touch your page or your servers, so your PCI scope stays exactly where it is: nowhere. The same wallet link works two ways. Text it to the user and it opens the hosted wallet page (an App Clip on iOS). Drop it into the SDK and the wallet opens inside your product. One mint, both surfaces.

The Wallet SDK is rolling out with design partners. It needs two things on your organization: wallet links enabled, and your page’s origin registered for embedding. Contact us and we will switch both on.

The shape

Your server mints a wallet link for a connected user: POST /api/v2/wallet_links with your client-credentials token.
Your page passes the link to AgentCard.create() and calls open().
The user attaches a card or approves a payment inside the sheet.
Your server hears the results on webhooks: connection.created, connected_card.updated, card.*, wallet_link.opened. Treat SDK events as UI signals and webhooks as the truth.

Quick start

Load the SDK from Agentcard on every page that uses it. Do not bundle or self-host the file: it is versioned at /js/v1/ and updates itself, which is how fixes reach your users without you shipping anything.

<script src="https://app.agentcard.sh/js/v1/agentcard.js"></script>

Mint the link server-side, hand its URL to the page, and open the wallet:

// Server (any language): mint with your org client-credentials token.
// POST https://api.agentcard.sh/api/v2/wallet_links
// { "user_id": "<connected user id>", "expires_in": 900 }
// -> 201 { id, url, status: "active", expires_at, test_mode }

// Browser:
const wallet = AgentCard.create({
  token: link.url, // the wallet link URL (or its raw token)
  onSuccess: (data) => {
    // { type: "card_attached", cards: [...] }
    // { type: "payment_completed", merchant, amount_cents }
  },
  onExit: () => {},
  onEvent: (name, data) => analytics.capture(name, data),
  onTokenExpired: async () => {
    const fresh = await fetch("/api/agentcard/wallet-link").then((r) => r.json());
    wallet.update({ token: fresh.url });
  },
});

wallet.open(); // overlay sheet
// or: wallet.mount("#wallet")  — inline, always visible

That is the whole integration. The link is safe to expose to the browser: it is a short-lived capability scoped to that one user’s wallet, not an API credential, and it expires (15 minutes by default, configurable with expires_in).

Opening the pay sheet

When your agent needs the user to approve a specific payment, open the wallet with a pay intent. The user picks a card and confirms the amount in one step:

const wallet = AgentCard.create({
  token: link.url,
  pay: { merchant: "DoorDash", amountCents: 2350 },
  onSuccess: (data) => {
    if (data.type === "payment_completed") markOrderPaid();
  },
});
wallet.open();

Some banks ask for an extra approval step. The SDK opens the bank’s page in a new tab (it cannot render inside a frame; banks forbid that) and the sheet waits with a check button until the approval lands. If the browser blocks the automatic tab, the sheet shows a “Continue to your bank” button instead, so the user is never stuck.

`AgentCard.create(config)`

Option	Type	What it does
`token`	string	The wallet link URL or its raw token. Required for the live wallet.
`pay`	object	`{ merchant, amountCents }`. Opens the pay sheet instead of the wallet.
`onSuccess`	function	A card was attached or a payment completed. Receives `{ type, ... }`.
`onExit`	function	The user closed the sheet.
`onEvent`	function	`(name, data)` stream of everything below, for analytics.
`onTokenExpired`	function	The link died. Mint a fresh one and call `update({ token })`.
`onOpenUrl`	function	Override how bank-approval URLs open. Default: a new tab.
`zIndex`	number	Overlay stacking. Default `2147483000`.

The returned handler: open() shows the overlay, mount(el) renders inline in your element, update(config) swaps the token or pay intent, exit() closes the overlay, destroy() removes everything and stops listening.

Events

Every event also arrives on onEvent(name, data):

Event	When
`ready`	The sheet booted and is safe to show.
`resize`	`{ height }` for sizing inline mounts.
`event`	Step stream (`step_changed`, `link_unavailable`, …).
`success`	`{ type: "card_attached" \| "payment_completed", ... }`.
`token_expired`	The link or session ended. Mint a fresh link, `update()`.
`open_url`	`{ url }` the host should open top-level (bank approval).

iOS, fully native

For iMessage-adjacent and native apps, AgentcardWalletKit renders the same wallet with native SwiftUI — no iframe, no loaders. Attach, the wallet, and the pay sheet are native screens calling the API directly; the only webview inside is the hosted card capture and bank ceremony, which keeps your PCI scope at zero. Available to design partners as a Swift package.

.sheet(isPresented: $showWallet) {
    AgentcardWalletSheet(
        link: link.url,
        pay: AgentcardPayIntent(
            merchant: "DoorDash",
            amountCents: 2350,
            reference: order.id  // your stable id for this payment
        ),
        onEvent: { event in
            if case .paymentCompleted = event { markOrderPaid() }
        }
    )
}

reference is your own id for the payment (an order or checkout id). It is what keeps two different payments with the same amount separate: retries of one payment reuse its reference, distinct payments never share one. Events mirror the web SDK exactly: ready, stepChanged, cardAttached, paymentCompleted, tokenExpired.

React Native

@agentcard/wallet-react-native wraps the same sheet for React Native apps (requires react-native-webview). Same wallet link in, same events out; bank approvals open in the system browser.

<AgentcardWallet
  link={link.url}
  pay={{ merchant: "DoorDash", amountCents: 2350 }}
  onSuccess={(d) => d.type === "payment_completed" && markOrderPaid()}
  onTokenExpired={() => refreshLink()}
/>

Testing

Mint wallet links with your sandbox credentials and everything runs in test mode end to end: the sheet shows test cards, attach completes instantly, and pay-sheet mints skip the bank approval. See Testing for the sandbox setup.

Instructions for your agent

Paste this into your coding agent to implement the embed.

Instructions for your agent

You are embedding the Agentcard wallet in our web product. Our server already
authenticates users with Agentcard (we have their user_id — see
/companies/api/user-authentication). Base URL https://api.agentcard.sh.

1. SERVER: add an endpoint that mints a wallet link for the signed-in user.
POST /api/v2/wallet_links   (Authorization: Bearer <org client-credentials token>)
{ "user_id": "<id>", "expires_in": 900 }
-> 201 { id, url, expires_at, test_mode }
Return { url } to our frontend. Never expose org credentials to the browser;
the link URL itself is safe (short-lived, single-user capability).
-> 403 wallet_link_unavailable or 422 user_info_required: surface the message;
   the account needs setup steps first.

2. PAGE: load the SDK from Agentcard (never bundle it):
<script src="https://app.agentcard.sh/js/v1/agentcard.js"></script>

3. OPEN: fetch the link from our server, then:
const wallet = AgentCard.create({
  token: link.url,
  onSuccess: (d) => { /* refresh our UI */ },
  onTokenExpired: async () => wallet.update({ token: (await mintFresh()).url }),
});
wallet.open();
For a specific payment add: pay: { merchant: "<name>", amountCents: <int> }.

4. TRUTH: subscribe to webhooks (connection.created, connected_card.updated,
card.*) for durable state; treat SDK onSuccess as a UI signal only.

5. GOTCHAS:
- Our page origin must be registered with Agentcard for embedding; until it
  is, the sheet will refuse to render (frame-ancestors).
- Do not open the wallet in a sandboxed iframe of our own; the SDK manages
  its iframe itself.
- Bank approvals open in a new tab via the SDK; do not block window.open for
  this flow.

Getting Started

Authentication

Guides

Webhooks

Funding options

Withdrawals

MCP

Examples

The shape

Quick start

Opening the pay sheet

`AgentCard.create(config)`

Events

iOS, fully native

React Native

Testing

Instructions for your agent

​The shape

​Quick start

​Opening the pay sheet

​AgentCard.create(config)

​Events

​iOS, fully native

​React Native

​Testing

​Instructions for your agent

The shape

Quick start

Opening the pay sheet

`AgentCard.create(config)`

Events

iOS, fully native

React Native

Testing

Instructions for your agent