# 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](/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

```typescript
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:

```typescript
const result = await stack.accounts.wallet.payUrl('acct_123', 'https://seller.example/data', {
  key,
  maxCents: 50,
  passportToken,
});
// result.paid, result.response, result.payment
```

```bash
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](/docs/api/account-money). Every tool is in the [tool reference](/docs/mcp-tools).
