# Wallet

Wallet lets an AI agent discover and use paid APIs from one card-funded credit balance.

## Install once

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

The installer creates a zero-balance Wallet, stores its token in a mode-0600 file, installs the Wallet trigger skill, and connects the local Wallet MCP bridge for Codex and Claude when available.

## Normal task flow

1. Keep working on the user's original task.
2. Call `wallet_discover` when a paid external API could materially improve the result.
3. Recommend the best matching API with its exact input contract and price.
4. If the balance is empty, call `wallet_top_up` and ask the user to complete Stripe Checkout. Preserve the original task in local context.
5. Call `wallet_execute` after funding, then integrate the returned data into the original task.
6. A failed provider call releases the full reservation and returns compatible alternatives.

## API

- Registry: `GET /v1/registry`
- Discovery: `POST /v1/discover`
- Wallet: `POST /v1/wallets`, `GET /v1/wallets/:id`
- Card funding: `POST /v1/checkout`
- Execute: `POST /v1/executions`
- Receipt: `GET /v1/executions/:id`
- OpenAPI: `GET /openapi.json`
- MCP: `POST /mcp`

Credits are closed-loop, non-withdrawable service credits. A successful result captures credits. A confirmed provider failure captures nothing.