# Wallet

**One API for everything your agent needs.**

Wallet is a skill and MCP bridge for Claude and Codex. It notices when an external capability can improve the user's current task, searches a live registry, explains the useful outcome and USD price, and uses the chosen service from one card-funded dollar balance.

Public product: `https://wallet.pact.sh`

## Install once

1. Create a Wallet at `https://wallet.pact.sh/wallet`.
2. Choose **Create pairing code**.
3. Install and claim the ten-minute code:

```bash
npm install --global git+https://github.com/learners-superpumped/api-mcp-pass.git
api-mcp-pass install --server https://wallet.pact.sh --host all --pair ABCD-EF12
```

The installer:

1. Connects the installed agent to the user's existing web Wallet.
2. Stores a separate agent token in `~/.wallet-pact/config.json` with mode `0600`.
3. Installs the proactive Wallet trigger skill for Claude and Codex.
4. Adds a local stdio MCP bridge. The Wallet token is never copied into chat or MCP configuration.

Installing without `--pair` remains available for machine-only setup and creates a new zero-balance Wallet.

## The user flow

A user asks an ordinary question such as: “Find recent Reddit complaints about AI coding agents and summarize the recurring problems.”

1. The Wallet skill recognizes that a live social-search API can materially improve the answer.
2. `wallet_discover` searches the registry and recommends the best API with its input contract, expected result, and USD price.
3. If the Wallet is empty, `wallet_top_up` returns a Stripe Checkout link. The agent preserves the original task.
4. After card payment, the funded dollar amount appears in the same Wallet and the agent resumes the task.
5. Wallet funds the user's managed payment address for that call, then `wallet_execute` signs and pays the selected x402 or MPP provider from that user-specific address.
6. A usable success captures the disclosed dollar amount. A confirmed provider failure captures nothing, releases the reservation, and returns compatible alternatives.

The current registry contains 37,529 uniquely addressable machine-readable operations across 1,969 services: 395 from six provider OpenAPI documents, 35,934 normalized x402 contracts from 1,832 Agentic Market services, and 1,200 unique MPP contracts from 137 services in the official mpp.dev catalog. Of those directory contracts, 35,326 x402 operations and 846 MPP operations publish a bounded price on an enabled network and are executable through the same Wallet gateway. HTTPS, method, price, currency, network, and maximum-spend checks fail closed; unsupported records remain discoverable but cannot spend credits.

## Credits

- One-time card funding: enter any amount from $5 to $1,000.
- Automatic recharge: choose a dollar balance threshold and a $5 to $500 recharge amount, then explicitly authorize off-session card charges. A failed charge adds nothing and pauses the feature.
- Public prices and balances are denominated in USD. The internal cent/atomic ledger remains closed-loop and cannot be withdrawn or transferred.
- Every Wallet has a distinct encrypted EVM signer stored in SQLite. Its public address is shown on the dashboard and is used on both Base x402 and Tempo MPP calls.
- Fixed-price calls show their exact price. Dynamic-price calls reserve the published maximum and capture only the amount verified in provider payment metadata.

## Product surfaces

- API explorer: `https://wallet.pact.sh/apis`
- Wallet dashboard: `https://wallet.pact.sh/wallet`
- Rewards and social verification: `https://wallet.pact.sh/wallet#rewards` (the legacy `/rewards` route remains available)
- The dashboard shows the user's provider-payment address, custom card funding, automatic recharge controls, current dollar balance, successful calls, a combined funding and usage ledger, and connected reward profiles.
- Stripe Checkout supports user-entered one-time amounts. Automatic recharge saves the card during its first paid Checkout and charges only after the chosen threshold is crossed.

## Agent interfaces

- Registry: `GET /v1/registry`
- Task discovery: `POST /v1/discover`
- Wallet: `POST /v1/wallets`, `GET /v1/wallets/:id`
- Web Wallet: `POST /v1/web/email/start`, `POST /v1/web/email/verify`, `GET /v1/me`
- Agent pairing: `POST /v1/web/pairings`, `POST /v1/pairings/claim`
- Card funding: `POST /v1/checkout`
- Disable automatic recharge: `POST /v1/auto-recharge/disable`
- Billing portal: `POST /v1/billing/portal`
- Execution: `POST /v1/executions`
- Agent guide: `GET /agent.md`
- OpenAPI: `GET /openapi.json`
- MCP manifest: `GET /.well-known/mcp.json`
- MCP transport: `POST /mcp`

## Pact Agent OAuth

Wallet is the authorization server for the unified Pact Agent start flow. The default registered client is `pact-agent`, with the single exact callback `https://agent.pact.sh/oauth/callback`. Production must set a 32-character-or-longer `PASS_OAUTH_PACT_AGENT_CLIENT_SECRET`; alternate exact callbacks can be supplied as a comma-separated `PASS_OAUTH_PACT_AGENT_REDIRECT_URIS` allowlist.

Pact Agent starts authorization with `GET /oauth/authorize` and these required query parameters: `response_type=code`, `client_id`, exact `redirect_uri`, `scope`, unpredictable `state`, `code_challenge`, and `code_challenge_method=S256`. A signed-out browser is returned only to the local `/wallet` email signup/sign-in UI, then resumes the same server-held, HttpOnly-cookie-bound request. Production session and authorization-transaction cookies use the `__Host-` prefix, `Secure`, `Path=/`, and no `Domain`, so a sibling `*.pact.sh` origin cannot toss a Wallet cookie. A signed-in user sees explicit consent. Approval redirects to the registered callback with `code` and the unchanged `state`.

The Pact Agent server exchanges that one-time 60-second code using an HTTP Basic client credential and either an OAuth form body or JSON body:

```http
POST /oauth/token
Authorization: Basic base64(pact-agent:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=oauth_code_...&redirect_uri=https%3A%2F%2Fagent.pact.sh%2Foauth%2Fcallback&code_verifier=...
```

```json
{
  "access_token": "wallet_oauth_...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "wallet:read wallet:reserve wallet:checkout",
  "sub": "wallet_..."
}
```

The access token is a separately digested, revocable grant. It is never an existing full `wallet_sk` token, and the OAuth response and scoped Wallet reads omit email and social identity. `wallet:read` authorizes `GET /v1/me` and the subject's `GET /v1/wallets/:id`; `wallet:checkout` authorizes `POST /v1/checkout`; `wallet:reserve` authorizes subject-bound reservation, debit settlement, and release. A reservation may declare a bounded `max_credit_atomic` ceiling so a verified Society, AgentPump, or Playground payout can use the same activity, but the OAuth bearer can never apply a positive credit settlement. Crediting verified service proceeds requires Pact Agent's separate server credential, so a self-asserted receipt cannot mint Wallet balance. Revoke the access token with authenticated `POST /oauth/revoke` and body `token=wallet_oauth_...`.

Provider dispatch is idempotent. Before dispatch, Wallet checks the user's address on the selected chain and transfers only the deficit needed for the provider's published maximum plus the Tempo fee buffer. The transfer and encrypted signer are persisted in SQLite. Credits are reserved before money moves, captured after a verified success, and released on a confirmed failure. If a process stops during funding or after provider payment, or dynamic price metadata cannot be verified, the reservation remains locked for reconciliation instead of risking a duplicate payment or an incorrect charge. A Pact that reaches `CANCELLED` with no deposits or payouts is the one safe automatic recovery case: the provider could not have been dispatched, so Wallet releases the reservation without retrying payment.

## Local verification

```bash
npm ci
npm test
```

The normal suite uses fixture providers and an isolated Pact 0.3.3 contract fixture. It validates per-call Pact settlement and refund without calling production or spending AgentCash funds.

An explicitly budgeted release canary spends one x402 and one MPP provider call from the configured AgentCash wallet:

```bash
AGENTCASH_LIVE=1 npm run test:sandbox
```

Production Wallet uses Pact 0.3.3 at `https://api.pact.sh` as an external API for every paid execution. Wallet deploys and serves discovery, signup, billing, and installation independently; immediately before provider dispatch it verifies Pact readiness and access, funds a dedicated Pact, settles it after a usable result, and completes a unanimous refund before releasing credits after a confirmed provider failure.

See [deployment](docs/deployment.md), [verification](docs/verification.md), [user scenarios](docs/user-scenarios.md), [design QA](design-qa.md), and [security](SECURITY.md).