Writing an x402 MCP Example That Does Not Read as a Price or a Payment
A useful x402 MCP example teaches two separate actions: discovering a tool and responding to a payment challenge. It must also avoid teaching a third, unintended lesson — that a sample amount, address or signature is a live price or a completed payment. This is a documentation-craft guide, not a payment instruction.
Put the fiction label above the snippet, not in a footnote
Readers copy from the first screenful. A footnote that says “example only” arrives too late. Put the label inside the code block or immediately above it: FICTITIOUS VALUES — NOT A PRICE, NOT A PAYMENT. State plainly that the sample is not a Skavio quote and not evidence of a transfer. Use an obviously synthetic reference and a zeroed address, and keep the sample away from any pricing table or invoice-like layout. If a figure could be pasted into a wallet without hesitation, the example is too realistic for documentation.
- Place the fiction label in the same visual unit as the snippet.
- Use a made-up reference such as DEMO-REF-NOT-A-PAYMENT and a zeroed address.
- Keep the sample away from price lists, quotes and invoice-like layouts.
Copy the schema; replace every value
Start with the documented schema, not with a shape that looks plausible. Open https://getskavio.com/x402/docs/ and copy the actual field names and types. Then replace every value that could be mistaken for live data: ```text # FICTITIOUS VALUES — NOT A PRICE, NOT A PAYMENT # Not runnable. Copy field names and types from the docs. { "<DOCUMENTED_AMOUNT_FIELD>": "<FICTIONAL_AMOUNT>", "<DOCUMENTED_RECIPIENT_FIELD>": "0x0000000000000000000000000000000000000000", "<DOCUMENTED_REFERENCE_FIELD>": "DEMO-REF-NOT-A-PAYMENT", "<DOCUMENTED_NETWORK_FIELD>": "<DOCUMENTED_NETWORK_VALUE>" } ``` This frame is deliberately not a runnable payload. It shows the discipline: real field names, fictional values and no implied wallet instruction. Add a warning not to send funds to any address shown in a sample. If the documented type is numeric, keep the sample value obviously non-market and keep the fiction label adjacent; do not break the schema with a string that makes the example misleading.
- Copy field names from the published documentation; do not invent a schema.
- Replace amounts, addresses and references with unmistakably fictional values.
- Warn readers not to reuse sample credentials or send funds to sample addresses.
Name the network and token in the prose
A stablecoin balance on one network is not the same balance on another network. The surrounding text should say which network the sample concerns, rather than leaving it to the reader’s assumption. Skavio x402 MCP combines an MCP interface with x402 v2 verification for native Circle USDC, public chain inspection and conditional Base USDC payment challenges. For supported wallets, supported networks and current payment handling, point readers to the published documentation. Do not imply partnership, endorsement, audit or certification by Circle, Base or any wallet provider. If the example concerns USDC, name native Circle USDC rather than reducing the asset to “stablecoin”.
- Write the network name in the surrounding prose, not only inside a payload.
- Name native Circle USDC where the example concerns USDC.
- Link to the published documentation for supported networks, wallets and current payment handling.
Show the unresolved state and the human decision point
Tool discovery and payment are distinct actions. Show them as separate steps: first the client discovers or inspects the tool, then the client encounters a conditional payment challenge. In the response-handling text, do not collapse “challenge received”, “verification pending” and “settled” into one success state. A signed payment challenge is not independently settled revenue. Do not write a sample that treats a signature or a broadcast transaction as a completed payment. Instead, have the client display a pending or unknown state and stop at a human decision point. That is the difference between a documentation example and an accidental operating instruction.
- Show tool discovery and payment as separate actions.
- Use pending, unknown and human-review states instead of automatic success.
- Do not treat a signature or broadcast as settled revenue.
A pre-publication checklist for an honest example
Before publishing, check the sample against the live documentation rather than against memory. Confirm that every field name matches the current page, that every value is visibly fictional, and that no number in the snippet could be read as a Skavio price. Confirm that the prose makes no fee, wallet-support, settlement or network-finality claim. Keep a clear documentation link and exactly one product CTA. Recheck that both https://getskavio.com/x402/ and https://getskavio.com/x402/docs/ return a public HTTP success response. Remove real credentials, wallet material and customer data. The finished example should be copyable in structure, but not reusable as a live instruction.
- Every field name checked against the live documentation page.
- No snippet number that could be read as a Skavio price.
- No fee, wallet-support, settlement or network-finality claim.
- A clear documentation link and one CTA to https://getskavio.com/x402/.
- Public HTTP success for both the product page and the documentation page.
- No real credentials, wallet material or customer data.