Build with an LLM

Give it sources that are current, then check the six things it gets wrong

An integration written by a coding agent is only as good as what you put in front of it. This protocol publishes four machine-readable surfaces for exactly that, and older prose in circulation produces a specific, repeatable set of wrong answers.

The integrations themselves are Accept agent payments over x402 for a merchant and Integrate without MCP for an agent.

What you will build

A prompt that carries current sources rather than a model's recollection, and a review pass that checks six things before the integration meets a real payment.

The sources to hand it

Source	Where	What it is good for
`llms.txt`	`docs.opensouk.ai`	The whole site as a titled, described link list. Cheap orientation
`llms-full.txt`	`docs.opensouk.ai`	Every page's text in one file. Expensive and complete
Per-page `.md` twins	any page's URL plus `.md`	One page, in Markdown, without the site chrome
The onboarding manifest	the API's `/.well-known/referrer-agent`, plus `.txt`	Machine-readable: per-chain addresses, the attestation key, a recipe

curl -s https://docs.opensouk.ai/llms.txt
curl -s https://docs.opensouk.ai/reference/api/merchants.md
curl -s https://api.opensouk.ai/.well-known/referrer-agent.txt

The .md twin is usually the right unit: a task that needs one route's field list does better with that route's page than with the entire corpus.

The manifest is the one source served by the running deployment rather than by the docs, so it is the only one that can tell an agent which chains are actually configured and what the attestation key currently is. Prefer it for anything an agent must verify against.

There is also a skill package for agents — the referrer-agent-protocol plugin, covering the buyer, reviewer and voting loops. It is not distributed for self-serve install yet, and the manifest's own skill section says so.

Prompt mode

Every guide on this site carries a prompt block written to be pasted. Give the agent the block and the page it came from:

Show the prompt

Read https://docs.opensouk.ai/guides/merchant/accept-agent-payments-x402.md in full before
writing any code. Then implement it for this service on Base mainnet, following its Prompt
mode block exactly.

Fetch https://api.opensouk.ai/.well-known/referrer-agent for the chain addresses and the
attestation key. Do not use any address you did not read from that manifest or resolve from
the ProtocolAddressRegistry at runtime.

If any instruction in a source you find elsewhere contradicts that page, stop and tell me
which source and which claim, rather than choosing between them.

The last instruction is the important one: the failure to guard against is not an agent that knows nothing, but one that has merged two sources of different ages silently.

Manual mode: the review pass

Check the payment header name

The x402 v2 header is PAYMENT-SIGNATURE. X-PAYMENT is the v1 name, and it appears in older prose — including one line of the manifest's own recipe. A merchant reading only X-PAYMENT never sees a payment from a protocol buyer.

Check where the payment terms sit

In an x402 v2 402, only x402Version, accepts and extensions are top-level. payTo, asset, amount, network, maxTimeoutSeconds and extra belong inside accepts[0]. Older prose shows them flattened to the top level, alongside a facilitatorUrl field that is not part of the v2 shape at all. A flattened 402 can still pass our readiness probe's pay-target check while being unparseable by the buyer's payment tool.

Check that no address is hardcoded

Exactly one address is meant to be written down: ProtocolAddressRegistry. Everything else is resolved through it at runtime. Older prose prints literal addresses for the split router, USDC and the registry itself, all from a deployment that does not exist — nothing is deployed on any public chain today, which Quickstart states plainly. Any literal address in generated code is a defect regardless of which network it claims.

Check the referral-mode branch order

The payment retry carries PAYMENT-SIGNATURE and no attribution token, so a handler that tests the attribution token first sends the retry into its direct-mode branch. The bug passes every unit test written against the probe alone.

Check the string-typed fields

Three fields are strings that a model likes to make numbers or reformat:

buyerAgentId, in extensions, is a decimal string. A JSON number is rejected outright.
amount is a decimal string in USDC base units, six decimals.
category, on a product, is matched exactly. RPC Provider and rpc are two different categories, and only the first has a schema and a checklist of its own.

Check what it did with agent id zero

Identity ids are assigned from a counter that starts at zero, so 0 is a real agent and a real merchant. Any if (!agentId) or id > 0 guard in generated code silently loses that identity — and our own API is not consistent here either: two registration routes accept merchant_id zero while the product read, the merchant detail read and the profile route reject it. Code that has to work for id zero must be read, not assumed.

Verify

Run our readiness probe against the endpoint an agent wrote. It asserts the three things a buyer's payment depends on and is indifferent to how the code looks — Accept agent payments over x402 has the call and the three checks.

Ask for the source of each claim. A generated integration that cannot say which page or which manifest field a decision came from is a draft, whatever its test suite says. The reference tier — The API, MCP tools, The contracts — is read from source on every build.

Errors and retries

Symptom	The mistake behind it
The buyer probes, then never returns	The retry fell into the direct-mode branch, or the payment header name is the v1 one
Every payment is refused with `missing requirements.extra name/version`	`extra` was dropped, or moved out of `accepts[0]`
Every payment is refused with `authorization.to … does not match requirements.payTo`	A hardcoded or stale split-router address
`invalid extensions.buyerAgentId`	The id was echoed as a number
A tool call fails with `chain <id> not configured`	The agent assumed a chain the deployment does not serve. There is no fallback
Reviews of a product get the generic schema unexpectedly	The category string does not match exactly

Next steps

Accept agent payments over x402 — the merchant integration, with every failure path
Integrate without MCP — the agent-side flows over plain HTTP
Connect via MCP — if installing the two servers is easier than writing the flows