# paymentrequired.com — wallet, card, banking and buying for AI agents

> WALLET + CARD + BANKING + BUYING for AI agents, over one MCP endpoint. No API
> key, no signup form. Base mainnet. Six tools: wallet, account, bank,
> browser, vault, inbox. A card number is never handed to the model.

## What it is — five tools, one endpoint

- **wallet** — the agent's own USDC wallet on Base. It exists from the first
  call, before any sign-in or identity check. It holds a budget and pays paid
  web links by itself. Until the person connects, the service holds the
  wallet's owner key for them.
- **account** — the identity check, the only step the person does on the web.
- **bank** — a Wirex-issued Visa card and a real EUR IBAN. Available once the
  identity check is approved; both are set up automatically on the first call
  after that. The model only ever sees the masked card — the full numbers
  appear on the approval page after the person signs there, and nowhere else.
- **browser** — buys something online for the person with their card, without
  anyone seeing the card number. A cloud browser goes to the shop, fills the
  card server-side and pays; the model gets `ordered`, `needs_human` or
  `failed`, never the number.
- **inbox** — sends and receives mail from this deployment's own domain, no
  third-party mail provider. `read` returns the messages addressed to one
  inbox (`support@` or `agent@`) and clears them; `send` mails one recipient
  after the person taps an approval link.
- **vault** — the person's private records (contacts, logins, agent memory) in
  an encrypted vault only their wallet can open. `put` stores a record, `get`
  decrypts one for this call only, `list` shows record ids without any value.
  `get` and `put` first need a fresh wallet signature: the first call returns
  an approval link; call again with the same reference to finish. `get` on a
  login never returns the secret — the model names the record, the browser
  fills it.

## Connecting is automatic — there is no connect tool

Call any tool. When the call needs the person connected, the result is:

```
{ status: "connect_required", approval_url, request_id, session,
  message: "First connect your wallet — open the link and approve. Then ask again." }
```

Show the approval_url unchanged. The person opens it and approves once. Then
call the SAME tool again with the `session` value from that result — or with
only the `request_id`; both wait quietly for the approval and then just run.
Keep the session private, reuse it until it expires, and never display it.
An expired session simply produces a fresh link on the next call.

## wallet — the agent's own wallet

Actions: `balance`, `fund`, `pay`, `send`, `stop`, `withdraw`.

- `balance` → `{ available, reserve?, address }`. `available` is what the
  wallet holds; `reserve` is what the person's verified account could move
  over today, and is absent before the identity check.
- `fund` → `{ funded, from: "wallet" | "reserve" | null, address, hint? }`.
  Three paths, tried in order: the connected wallet holds USDC and sends some
  over; the person is verified and the reserve refills the wallet; otherwise
  `funded: false` with the address and the hint "Send USDC to this address to
  start".
- `pay(url, amount)` → pays a paid https link. When the balance is short it
  tries the same top-up paths first. One response: a receipt
  `{ status: "paid", transaction, resource }`, or one error sentence plus the
  next action.
- `send(to, amount)` → sends an amount to any address, owner only. One
  response: `{ status: "sent", receipt: { tx, amount, to } }`, or one error
  sentence plus the next action.
- `stop` ends the agent's access to the wallet. `withdraw` sends what remains
  back to the person. `send`, `stop` and `withdraw` belong to the connected
  owner.

## account — the identity check

Actions: `status`, `verify`.

- `status` → `{ verified, kyc_url? }`.
- `verify` → the identity-check link. Hand it to the person unchanged; it is
  the only human step between them and the bank features.

## bank — card and euro account (needs verified)

Actions: `card`, `iban`, `send`, `push`.

- `card` → the masked card (`**** **** **** 1234`) plus an approval link. The
  full numbers show on that page only, after the person signs; your result is
  always the masked card and never the number.
- `iban` → the euro account details (IBAN, BIC).
- `send` → a euro transfer to a bank account. Show the exact amount and
  recipient first; send only after the person says yes to that exact transfer.
- `push` → a push-to-card payout: euros to a saved card. Show the exact amount
  and the fee first; send only after the person says yes to that exact payout.
  The card is always masked (last four digits only).

## browser — buy online with the card (needs verified)

Action: `buy`.

- `buy(url, max_amount)` → opens a cloud browser that goes to the shop, fills
  the card (server-side, never shown) and pays. It answers
  `{ status: "ordered" | "needs_human" | "failed", summary, live_url?, approve_url? }`.
- `ordered` → the browser is at the checkout; the person can watch at `live_url`.
- `needs_human` → the person must open a link: to approve using the card, or to
  finish a step the shop needs from them (a phone code, 3-D Secure or a login).
- `max_amount` is the most this one purchase may cost; it never goes above the
  limit this service allows. The full card number, expiry and security code
  never appear in any answer.

## inbox — send and receive mail from this deployment's own domain

Actions: `read`, `send`.

- `read(inbox)` → the messages addressed to `support@` or `agent@` on this
  deployment's own mail domain, newest first, `{ count, messages }`. Reading
  clears them — a body lives only for that one call.
- `send(to, subject, body)` → a write, so the first call returns an
  `approval_url` the person taps, plus a `request_id`. Repeat the same call
  with that `request_id` to send. Mail goes out through the Cloudflare Email
  Service on our own domain.

## Errors

Every error is one sentence plus the next action. Do that one thing; never
retry blindly, and never invent an approval link or a failure reason.

## Quickstart — the first calls an agent makes

- What can this wallet do? → wallet {action:"balance"} (no sign-in needed)
- Top it up → wallet {action:"fund"} → `{ funded, from, address, hint? }`
- Pay a paid link → wallet {action:"pay", url, amount} → a receipt or one
  error sentence
- Who am I / get me a card and IBAN → account {action:"verify"}, then bank
  {action:"card"} or bank {action:"iban"} once verified
- Any result with status connect_required → show the link, then call the same
  tool again with the session from that result

## Connect

MCP endpoint: https://paymentrequired.com/mcp
Transport: JSON-RPC 2.0 over HTTPS (MCP Streamable HTTP). No auth header — the
session comes from the automatic connect flow above. Add the URL as a remote
MCP server in Claude, Cursor, Hermes, Codex or any MCP client. Nothing else to
configure.

How the person signs in: they tap the link. That is the default and it is
enough.

## Start prompt (paste this into your agent)

Connect on paymentrequired.com and tell me what I can do — wallet, card and
bank account. Whenever you get a link, show it to me unchanged. Before any
money moves, show me the exact amount and recipient and wait for my yes.

## Five rules

- One link at a time. Show approval links unchanged. Never ask the person to
  prove they tapped — call the tool again; the server waits by itself.
- Money moves only after the person says yes to the exact amount and
  recipient.
- Every refusal names the next step. Do that one thing.
- Never repeat the session string, a card number or a security code unless the
  person asked in this conversation.
- Pending is not done. Say "done" only when the result says paid or completed.

## Reference

- Every tool and field, generated from the live server: https://paymentrequired.com/llms-full.txt
- Agent quick reference: https://paymentrequired.com/llms-agents.txt
- Paid services an agent can use right away, per call, no account: https://paymentrequired.com/llms-services.txt
- Same as JSON: https://paymentrequired.com/services.json
- Health and version: https://paymentrequired.com/healthz
- Long-form integration guide: https://paymentrequired.com/docs
- Source: https://github.com/nuri-com/agent-payments-mcp-wirex