Wallet

Every method takes the identity (an idn_… id or its name) as its first argument. Amounts are integer micro-USD (1 USD = 1_000_000). A persona holds at most one live wallet per network. create names the network in its body; every other method takes a trailing { network } selector (or network alongside the list filters) and works on the testnet wallet (eip155:84532) when it is omitted. No method falls back to the other network: a read on a network with no wallet is not_found.

const wallet = client.identities.wallet

const created = await wallet.create(identityId, {
  network: "eip155:84532", // Base Sepolia, the default
  policy: { per_tx_cap_micro_usd: 500_000, daily_cap_micro_usd: 20_000_000, low_balance_micro_usd: null },
})
const current = await wallet.get(identityId) // the testnet wallet; balance_micro_usd is live

await wallet.updatePolicy(identityId, { per_tx_cap_micro_usd: 1_000_000 })
await wallet.freeze(identityId)
await wallet.unfreeze(identityId)

// The same persona's mainnet wallet, once the organization has enabled mainnet.
const mainnet = await wallet.create(identityId, { network: "eip155:8453", policy: { per_tx_cap_micro_usd: 250_000 } })
await wallet.get(identityId, { network: "eip155:8453" })
await wallet.freeze(identityId, { network: "eip155:8453" })

Move funds:

await wallet.fund(identityId, { amount_micro_usd: 1_000_000, source: "faucet" }) // testnet only; the faucet grants a fixed 1 USDC
await wallet.transfer(identityId, { to: "0x…", amount_micro_usd: 250_000, purpose: "API credit" }) // or a sibling `idn_…`
await wallet.sweep(identityId, { to: "0x…" }) // omit `to` for the treasury (501 until one is provisioned); retires the wallet
const history = await wallet.transactions(identityId, { kind: "transfer", direction: "out" }) // add `network` for the mainnet ledger
for (const tx of history.data) tx.amount_micro_usd // integer micro-USD, `tx.tx_hash` once confirmed

Pay for a paywalled resource — quote has no side effects, pay spends under the wallet’s caps:

const quote = await wallet.quote(identityId, { url: "https://api.example.com/report" })
if (quote.payable && quote.amount_micro_usd! <= 250_000) {
  const payment = await wallet.pay(identityId, { url: quote.url, max_amount_micro_usd: 250_000 })
  payment.paid // true; `payment.transaction_id` is the `wtx_…` receipt
  payment.response_body // the paid resource, up to 64 KiB
}
const receipts = await wallet.receipts(identityId, { since: "2026-09-01T00:00:00Z" }) // transactions with kind "pay"

Every POST carries the client’s Idempotency-Key, so a retried fund, transfer or pay returns the first attempt’s transaction rather than moving money twice. A short balance is an ApiError with code validation_failed, never insufficient_credits; a deployment without custody answers feature_not_configured. See the Wallet API for statuses, scopes and errors.

TypeScript

Control plane

Resources

Identity & access

Automation

Account