USDC wallet
How you give an agent a USDC wallet that you own, how the agent pays from it, and how you limit what it can pay. What the wallet is and what it costs is on Services.
Before you start
- The wallet is on Base and holds USDC. You are its owner. STACK holds no key to it.
- The agent has a key of its own that can only sign USDC payments from this wallet. It makes that key itself and keeps the private half.
- The wallet is made when the account is opened. Limits are optional and need controls. Without a limit, the USDC in the wallet is the most the agent can pay.
Become the wallet's owner
Once, as the owner or an admin, sign in to the wallet provider, Privy, on the wallet page of the Console. It is an email sign-in. From then on you are the owner of every wallet opened for your account. Until you have done this, a wallet waits, and its details carry owner_link_url with the address of that page.
The owner is set once and cannot be changed. There is no tool or terminal command for this step: it happens in your browser.
Open an account with a wallet
import { Stack, generateAgentWalletKey } from '@getstackrun/sdk';
const key = generateAgentWalletKey();
// Keep key.exportPrivateKey() in the agent's own secret store.
await stack.accounts.open({
name: 'buyer',
wallet: {
agent_public_key: key.publicKey,
per_payment_cap_usdc: 5,
daily_cap_usdc: 20,
},
}, { idempotencyKey: 'open-buyer-0001' });
- per_payment_cap_usdc is the most one payment can be. daily_cap_usdc is the most in any 24 hours. Both are optional, and they apply while controls are on.
- Set, change or remove a limit later with stack_set_wallet_caps or stack.accounts.wallet.setCaps. Only the owner or an admin can, and it needs controls.
- An account opened without a wallet, and without skip: ["wallet"], shows its wallet as failed. Name one or skip it.
- When the wallet is ready, its details carry the address. Send USDC on Base to that address to fund it.
Pay a seller
A seller that takes payment over x402 answers a request with what it costs. The agent pays and gets the answer in one step:
const result = await stack.accounts.wallet.payUrl('acct_123', 'https://seller.example/data', {
key,
maxCents: 50,
passportToken,
});
// result.paid, result.response, result.payment
npx @getstackrun/cli pay acct_123 https://seller.example/data --max-cents 50 \
--wallet-key-file ./agent-wallet.key --passport-stdin
- maxCents is the most the agent will pay for this request. A higher price is refused before anything is signed.
- The agent signs the payment with its own key. STACK checks it, against your limits where you set any, and only then passes it on. A refused payment is never sent.
- With the agent on "ask first", a payment waits for you: it is refused with 403 CONTROL_DENIED, reason review_required, and a ref. Once you approve, the agent sends the same signed payment again with that ref (control_ref on the tool).
- Each signed payment can be used once.
- The tool is stack_request_wallet_payment. To sign and send in two steps from code, use signWalletPayment and stack.accounts.wallet.pay.
Only the account's own agent can pay a seller from its wallet, with its Passport. A chat sign-in cannot. As the owner you can send USDC out of the wallet yourself, on the wallet page of the Console.
Stop payments
Closing the account stops payments at once. The USDC stays in the wallet, which is yours: send it out on the wallet page of the Console. To change the agent's key, close the account and open a new one.
What counts as an action
Each payment is one action. STACK takes nothing from the amount paid.
When a payment is refused
- 403 WALLET_PAYMENT_REFUSED, reason over_per_payment_cap or over_daily_cap - the payment passes a limit you set.
- 400 WALLET_PAYMENT_REFUSED, reason not_base_usdc - only USDC on Base can be paid.
- 400 WALLET_PAYMENT_REFUSED, reason authorization_window - the signed payment must expire within ten minutes.
- 403 WALLET_PAYMENT_REFUSED, reason agent_signature_invalid - the signature is not from the agent's key.
- 409 WALLET_PAYMENT_REFUSED, reason replayed - that signed payment was already used. Sign a new one.
- 409 ACCOUNT_PIECE_NOT_READY - the wallet is not ready, for example it waits for you to become its owner.
- 403 WALLET_PAYMENT_REFUSED, reason wallet_closed - the agent's key was removed from the wallet.
- 402 AGENT_BUDGET_EXCEEDED - the agent has a budget and it cannot cover the payment.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as wallet.payment, with the payee and the amount. A policy can hold a payment over an amount for your review.
Reference
Every field is on Wallet, RentAHuman and Getting Paid. Every tool is in the tool reference.