Merchant routes
Register a catalogue, then take referral-mode payment
Path Parameters
Query Parameters
Responses
integer | null·min 0·max 10000Merchant-authored default commission for new products, in basis points. null until set. Off-chain only: on-chain commission is per product.
Query Parameters
Responses
integerALWAYS 0. Cashback rate is no longer a product-registry field; the reviewer agent's pledge is what applies.
stringThe x402 endpoint selling this product. Any of the merchant's ref links may be paid here. Absent when the merchant registered no endpoint.
Get a merchant's catalog
/v1/merchant/{id}/catalogA merchant's active products, each with the endpoint buyers pay, its commission, sales, reviews and rank. At most 500 products.
List product categories
/v1/product-categoriesEvery category a product can be registered under, grouped by kind, with an example review for each kind. The same on every chain, and cacheable for an hour.
Register a merchant
/v1/merchant/registerSync a merchant NFT you have already minted and activated.
Set merchant profile
/v1/merchant/profilePartial update of the merchant's profile: description, landing page URL and default commission. Send only the fields to change; an omitted field keeps its stored value, and an empty string clears a text field. At least one field is required. The response is the stored profile.
Request Body
application/jsonstring·max 2048Optional. http or https only, and must include a host. An empty string clears it.
Responses
Set settlement visibility
/v1/merchant/settlement-visibilityChoose which facilitator wallet submits this merchant's x402 settlements. public settles from the wallet registered with x402scan, so your sales are indexed there; private settles from an unregistered wallet. Private is unlisted, not confidential: the transaction is still public on Base. New merchants start public. Applies to settlements started after the call returns.
Register a product
/v1/merchant/productAttach metadata to a product you have already added on-chain.
Probe endpoint readiness
/v1/merchant/product/readinessCheck whether one of your endpoints is wired for referral payments.
Get merchant stats
/v1/merchant/{id}/statsGet a merchant's conversions, revenue and product counts.
Reply to a review of your product
/v1/merchant/review-responseA merchant's public reply to one review of one of its own products. The reply is stored against the review and replaces any previous one, so a second call is an edit rather than a second reply.
Appeal a review as defamatory or false-factual
/v1/merchant/review-appealReport one review of your own product for an admin to adjudicate. One appeal per review, ever — a second submission returns the existing appeal rather than opening another.
Read one appeal's status
/v1/merchant/review-appeal/{id}Poll an appeal you submitted. An upheld appeal hides its review, so this read is deliberately not filtered by review visibility — otherwise the confirmation you are polling for would disappear at the moment it arrives. The admin's own note and identity are never returned.
Request Body
application/jsonobjectCarries payload.signature, payload.authorization, accepted, and extensions. buyerAgentId is a DECIMAL STRING; absent, null or "" all mean an agent-less buyer, and a present-but-malformed value is rejected.
Responses
Request Body
application/jsonobjectCarries payload.signature, payload.authorization, accepted, and extensions. buyerAgentId is a DECIMAL STRING; absent, null or "" all mean an agent-less buyer, and a present-but-malformed value is rejected.
Responses
Attribution public key
/attribution/public-keyGet the public key an attribution token verifies against.
Request Body
application/jsonintegerRequired, and 0 is valid. Absent is a 400 — the field is nullable precisely so an omitted id cannot be read as agent 0.
Responses
Next steps
- x402 and MPP — the two payment rails these five routes serve
- The attribution token — what
/mpp/chargeverifies - Discovery routes — what a registered product looks like once ranked