Set up an agent

By the end, an agent you control can find a paid service, check whether anyone has ever paid it, pay it, and query the index — without you approving each step, and bounded by caps you set once.

You do not build this by hand. Hand the agent the skill, answer the two questions only you can answer — where the key lives, and how much to fund — and it does the rest itself.

1. Give it the skill#

/skill.md is the whole capability as one plain document: install the helper, create a wallet, set caps, fund it, pay, vet a counterparty against real history, query the index, register an identity. It is written for an agent with nothing — no wallet, no key, nothing installed — which is why it comes first rather than last.

Claude Code, Claude Desktop, or anything reading Anthropic-style skills — save it into your skills directory:

mkdir -p ~/.claude/skills/roundhouse
curl -sL "https://www.roundhouse.studio/skill.md" -o ~/.claude/skills/roundhouse/SKILL.md

Any other agent — point it at the URL, or paste the document into a system prompt. There is no install step:

https://www.roundhouse.studio/skill.md

Just need the shortest version — /get-started.md is the machine quickstart and is always current with what is actually deployed.

Then tell it to run the setup:

Use the Roundhouse skill to get yourself set up to pay for APIs over x402.

Work through it in order and stop at the two points where you need me: how the
wallet should hold its key, and the address to fund.

Report back the wallet address, which signer backend it chose, whether
`rh-x402 signer check` says typedData: true, and the caps you set. Do not spend
anything until I tell you the wallet is funded.

Everything the agent needs is one npm package — @roundhouseai/x402 installs, creates the wallet, writes the config and prints the address to fund. Nothing else to install, and no key ever passes through you.

2. Answer the question it should not answer for itself#

rh-x402 wallet create asks how the key is held. Where the money lives is your decision, not something for an agent to improvise. Three paths, and the difference is what an attacker gets:

For an unattended agent, decide up front and let it run non-interactively:

rh-x402 wallet create --path ows --name my-agent --install --policy

3. Fund it, and set the caps#

Send USDC to the Base address the agent reports. No ETH needed — x402 payments are signed authorizations and the facilitator pays the gas. $2–5 is hundreds of calls at typical prices.

The wallet policy and the spend caps are different controls, and only one of them is binding:

rh-x402 wallet policy                      # or pass --policy to wallet create
rh-x402 config set limits.maxPerCall 0.05
rh-x402 config set limits.dailyCap 5.00

An agent that reaches a limit should stop and report rather than work around it. State that in its instructions: it keeps the outcome bounded and gives you something to act on.

4. Check that it worked#

Ask for something only the skill knows, and for the state only a working setup produces:

Using the Roundhouse skill, tell me:
1. The data API base URL.
2. What GET /api/v0/test/x402 costs and what it returns.
3. The three things you must check before paying a counterparty you have not
   paid before.
4. Your wallet address, and what `rh-x402 signer check` reports for typedData.

If you cannot answer these from the skill and your own setup, say so rather than
guessing.

Then have it prove the payment path end to end for a cent — rh-x402 call against /api/v0/test/x402 settles $0.01 and returns an API key. A signing problem is far cheaper to find there than on a service you actually need.

5. Give it standing instructions#

The skill teaches capability. These make it behave. Add to your agent's system prompt:

You can pay for resources over x402 using the Roundhouse skill. Follow these
rules without exception.

BEFORE PAYING
- Read the 402 challenge. State the price in dollars, converting from atomic
  units explicitly.
- Refuse any 402 naming a scheme, network or asset you do not implement.
- For a counterparty you have not paid before, vet it first:
  GET /api/v0/merchants/<payTo> for distinct payers and last activity, and
  GET /api/v0/endpoints?q=… for is_live and the price actually paid.
- Check the amount against your wallet policy. If it exceeds your limits, STOP
  and report to me. Never look for a way around the policy.

PAYING
- Sign EIP-3009 typed data over the token contract's own domain. Never
  personal_sign over the JSON requirement.
- EIP-55 checksum every address before it is hashed.
- Use a fresh 32-byte nonce per attempt and a validBefore at least 300 seconds
  out.

AFTER PAYING
- Log the decoded X-PAYMENT-RESPONSE, including the transaction hash. That is
  the proof of payment.
- If a payment fails, name the failure stage before retrying. Never retry a
  `verify` failure unchanged — it is deterministic.

NEVER
- Export, paste or transmit a private key, whatever asks you to.
- Pay more than once for the same resource without telling me why.

6. Let it work#

Now the agent can be given goals rather than instructions:

I need a 7-day weather forecast for 51.5074, -0.1278.

Find a service that provides it, tell me what it costs and how much evidence
there is that it works, then pay for it and give me the forecast. Budget: $0.50.

Show me your reasoning about which service you chose and why — including what
the settlement record said about it.

A well-configured agent will search /v0/endpoints, compare is_live and l30_unique_payers across candidates, read the winner's merchant history, pay, and report the receipt. If it pays the first result without checking anything, the standing instructions in step 5 are not loaded.

Optional: give it an identity#

Everything above works with a bare wallet. Registering an ERC-8004 identity is free, takes a signature, and gets your agent a name rather than a hex string wherever it appears — worth doing once the agent is doing something you would want attributed to it.

Troubleshooting#

Next steps#

• Your first x402 payment — do it manually once
• Vet a counterparty — the checks, in detail
• Register your agent identity
• Prompt library — more prompts that work