For agents

Prompt library

Copy-paste prompts for discovery, vetting, paying, querying and registering.

Each of these assumes the agent has either the Roundhouse skill loaded or the ability to fetch /skill.md. They are written to produce checkable output rather than confident narration — every one asks for the evidence alongside the answer.

Discovery#

Find a service and choose on evidence rather than on listing copy.

Agent prompt
Find a service that can <do the thing> and choose one on evidence.

1. Search GET https://www.roundhouse.studio/api/v0/endpoints?q=<terms>&limit=20
2. For each candidate, report: service_name, resource, price_usdc, is_live,
   http_status, last_indexed_at, l30_total_calls, l30_unique_payers.
3. Discard anything with is_live false, or last_indexed_at older than an hour.
4. Rank the rest by distinct payers over the last 30 days, not by volume and not
   by price.
5. For your top choice, fetch GET /api/v0/merchants/<pay_to> and tell me when it
   was last paid and by how many distinct wallets.

Recommend one and say what the listing claims that the settlement record does
not support.

Vetting#

Before paying someone new. The long form is in vet a counterparty.

Agent prompt
Vet this counterparty. Report each check with evidence, then recommend.

payTo: <0x…>
Proposed payment: <$…>

1. GET /api/v0/merchants/<payTo> — distinct payers, last settlement, volume.
2. GET /api/v0/endpoints?q=<service> — is_live, listed price versus paid.
3. GET /api/v0/agents/<payTo> and read erc8004_agents — which registry entries
   claim this wallet? If they claimed an agentId, check it is one of them and
   that its chain matches. Flag any mismatch.
4. Fetch their 402 live and confirm scheme, network and asset are ones I can pay.

Recommend: proceed, proceed with a cap (say what cap), or refuse. Name the single
check that decided it. Absence of history is a reason for a cap, not a refusal.

Paying#

One-shot payment with the guard rails stated.

Agent prompt
Pay for <resource URL> over x402 and give me what it returns.

Before paying:
- Read the 402. State the price in dollars, converting from atomic units
  explicitly so I can check the arithmetic.
- Confirm the scheme, network and asset are ones you implement. If not, stop.
- Confirm the amount is within my budget of <$…>. If not, stop and tell me.

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 hashing.
- Fresh 32-byte nonce; validBefore at least 300 seconds out.

After:
- Show me the decoded X-PAYMENT-RESPONSE including the transaction hash.
- Then give me the resource.

If it fails, name the stage. Do not retry a `verify` failure.

Querying#

Ask the index a question in SQL.

Agent prompt
Answer this from the Roundhouse index using POST /api/v0/sql:

<question>

Constraints the runner enforces:
- One statement, SELECT or WITH only. No semicolons, no comments.
- 300 rows maximum, 8-second timeout.
- Always filter settlements on block_time — it is the indexed column.
- Addresses are stored lowercase.
- verified_x402 is three-valued: true (proven), null (unexamined), false
  (disproven). Filter on true when the answer must mean "proven".
- mv_entity_rollups has no display_name — join entities for names.

Show me the SQL before running it, then the result, then what the result does
not tell me.

Market research#

The kind of question the index exists for.

Agent prompt
Research the market for <category> services on x402 and give me a briefing.

Use POST /api/v0/sql. I want:
1. How many distinct services in this category have been paid at all in the last
   30 days, versus how many are merely listed.
2. The price distribution of what is actually paid — not what is listed.
3. The repeat-customer rate across the category (payers with more than one
   settlement, as a percentage).
4. Whether the trend over 90 days is up or down, from mv_entity_daily.
5. The three most-paid services, with distinct payer counts.

State any figure that is a floor rather than exact, and say why.

Registering an identity#

Agent prompt
Register an ERC-8004 identity for me through Roundhouse.

1. GET /api/fn/register and show me the descriptor.
2. Draft an agent card: name, description, capabilities, x402 endpoints. Show it
   to me before signing anything.
3. Canonicalise it (keys sorted at every depth, no whitespace), sha256 it, and
   sign roundhouse-register:<hash>. Print the hash so I can verify it myself.
4. POST address, card and signature. Show me the hosted card URL.
5. Report whether onchain.sponsored is true. If false, give me the exact
   transaction to send and do not attempt to broadcast it.

Paying another agent#

Agent prompt
Send <amount> USDC on Base to <0x…> using the Roundhouse gasless forward.
Memo: <text>

1. GET /api/fn/gasless-usdc-forward and show me the descriptor. Report
   price.free.
2. Build the authorization. value is base units with 6 decimals — show me the
   conversion.
3. Sign TransferWithAuthorization over the domain from the descriptor, not a
   hard-coded one.
4. POST to /api/fn/gasless-usdc-forward/transfer. If price.free is false, expect
   a 402 for the fee first and pay it.
5. Show me the txHash and confirm the settlement is indexed at
   GET /api/v0/entities/<my wallet>/settlements.

Debugging a failed payment#

Agent prompt
An x402 payment is failing. Diagnose it without retrying blindly.

1. Show the raw 402 body, decoded.
2. Show the X-PAYMENT envelope you built, base64-decoded, and confirm:
   - value is atomic units as a string
   - to equals the requirement's payTo, EIP-55 checksummed
   - validBefore is at least 300 seconds in the future
   - nonce is 32 fresh random bytes
3. GET /supported on the facilitator and confirm the scheme and network you are
   using appear in it.
4. Name the failure stage. If it is `verify`, do not retry — tell me which of the
   four deterministic causes it is.

Monitoring your own spend#

Agent prompt
Reconcile my x402 spending for the last 30 days.

My wallet: <0x…>

1. From my own logs, total what I believe I paid and how many calls.
2. From POST /api/v0/sql, get the settlement count and summed amount_usd for
   payer = lower('<0x…>') over the same period.
3. Compare. Explain any difference, considering that:
   - amount_usd is NULL for unpriced tokens, so the index sum is a floor
   - the index may have an open gap — check /status
   - more rows in the index than in my logs means something else is paying from
     my address

Give me a table: my figure, the index figure, the difference, and the likely
cause.

Writing your own#

Four things every prompt above does, worth keeping when you write your own:

  1. Ask for the evidence, not just the answer. "Report is_live and payer counts" beats "find a good service".
  2. State the stop conditions. An agent that knows when to stop and report is worth more than one that always produces something.
  3. Name the constraints it will otherwise discover. The SQL limits, the atomic units, the checksumming — cheaper to state than to debug.
  4. Ask what the answer does not tell you. It is the single most useful line in any of these.

Next steps#