Agent-ready x402 postcards on Nuri

TL;DR

1. Point an agent to /api/x402; it discovers the postcard service and its complete schema.
2. The agent supplies only a public image URL, message and postal recipient.
3. Nuri automatically uses emino.nuri.eth as the service seller and creates the operation ID.
4. x402 settles the thanks.io cost plus 21%, then Nuri sends and tracks the 4x6 postcard.

Endpoints

Request

The paid endpoint accepts one explicit service request. The same JSON must be retried after the HTTP 402 response.

{
  "front_image_url": "https://example.com/postcard.jpg",
  "message": "Hello from Nuri.",
  "handwriting_style_id": 4,
  "size": "4x6",
  "recipient": {
    "name": "Example Person",
    "address": "1 Main Street",
    "city": "Berlin",
    "province": "BE",
    "postal_code": "10115",
    "country": "DE"
  }
}

Payment and fulfillment flow

1. PrepareValidate image, message and postal recipient; choose the configured seller, resolve ENS, derive the operation ID and persist only the hash plus payout terms.
2. ChallengeReturn HTTP 402 with x402 v2, Base USDC, scheme upto, the pinned payTo address, a $3.50 ceiling and required payment-identifier.
3. VerifyThe buyer retries the identical JSON with PAYMENT-SIGNATURE. The facilitator verifies the signed maximum before fulfillment begins.
4. FulfillSubmit exactly one 4x6 postcard to thanks.io. The response supplies authorization_total in cents.
5. SettleRound authorization_total × 1.21 up to the next cent and settle only that USDC amount to the pinned seller address.
6. TrackReturn a random public order ID. Status exposes delivery counts and transaction evidence, never the recipient address.

Idempotency, failures and privacy

The request needs both an application operation_id and x402 payment-identifier. Nuri stores a SHA-256 request fingerprint, never the recipient address. A hard settlement failure triggers immediate thanks.io cancellation. A broadcast settlement_pending transaction enters reconciliation instead of being treated as failed.

Public status exposes payment and delivery evidence without recipient PII.

Current boundary

• Agents do not need to know or submit a seller; emino.nuri.eth is configured for this postcard service.
• A postal recipient address remains required because thanks.io must physically deliver the card.
• Only the reviewed thanks-postcard-v1 adapter is active.
• One recipient and 4x6 Standard Mail only; no mailing lists, radius search or arbitrary callbacks.
• The receiving wallet supplies no private key. The address is a payment destination only.
• This is a reusable payment and fulfillment seam, not an unmoderated arbitrary-offer marketplace.

Discovery and market listing

• Nuri catalog: /api/x402 lists active paid services and adapter boundaries.
• Agent discovery: OpenAPI, llms.txt, Markdown negotiation and /.well-known/agentic-commerce.json expose the endpoint immediately.
• Bazaar declaration: every 402 challenge includes a typed Bazaar body schema, service name and tags.
• External market listing: a paying client must echo the Bazaar extension through a supporting facilitator; verify /discovery/resources before claiming listed.

Current evidence: Nuri-owned discovery is live. External Bazaar inclusion still needs one funded client to echo and settle the Bazaar extension before we claim the endpoint is listed.

Add the next paid endpoint

1. Define one fulfillment adapter ID, one bounded input schema and one authoritative cost source.
2. Configure seller normalization and ENS resolution inside the adapter so ordinary buyers never enter a seller.
3. Choose exact for known prices or upto for metered prices, then bind operation ID, payment ID and request fingerprint.
4. Publish OpenAPI, llms, agentic-commerce and Bazaar input/output examples with descriptions for every field.
5. Prove zero side effects before payment, one side effect under concurrent retries, public status, then one funded canary and Bazaar lookup.