---
title: "Agent-ready x402 postcards on Nuri"
description: "An agent supplies the postcard image, message and postal recipient. Nuri handles the seller, idempotency, x402 payment and thanks.io fulfillment."
type: api-documentation
updated: 2026-08-21
---

# Agent-ready x402 postcards on Nuri

An agent supplies the postcard image, message and postal recipient. Nuri handles the seller, idempotency, x402 payment and thanks.io fulfillment.

## TL;DR

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

## Endpoints

- `GET /api/x402` — Service catalog, protocol metadata and schemas.
- `GET /api/x402/resolve/{username}` — Resolve a Nuri username to its current ENS EVM address.
- `POST /api/x402/postcards/preview` — Render a thanks.io preview. It never mails a card.
- `POST /api/x402/postcards` — Create the x402 offer, verify payment, send one postcard and settle.
- `GET /api/x402/orders/{publicOrderId}` — Read privacy-safe payment and delivery status.

## Request

```json
{
  "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. **Prepare.** Validate image, message and postal recipient; choose the configured seller, resolve ENS, derive the operation ID and persist only the hash plus payout terms.
2. **Challenge.** Return HTTP 402 with x402 v2, Base USDC, scheme upto, the pinned payTo address, a $3.50 ceiling and required payment-identifier.
3. **Verify.** The buyer retries the identical JSON with PAYMENT-SIGNATURE. The facilitator verifies the signed maximum before fulfillment begins.
4. **Fulfill.** Submit exactly one 4x6 postcard to thanks.io. The response supplies authorization_total in cents.
5. **Settle.** Round authorization_total × 1.21 up to the next cent and settle only that USDC amount to the pinned seller address.
6. **Track.** Return a random public order ID. Status exposes delivery counts and transaction evidence, never the recipient address.

## Pricing

The endpoint uses x402 v2 `upto` on Base. The buyer authorizes at most **$3.50 USDC**. Nuri settles only:

`ceil(thanks.io authorization_total × 1.21)`

Example: thanks.io returns `252` cents. Nuri settles `305` cents, or `3,050,000` USDC atomic units, directly to the ENS-resolved seller address.

## Automatic seller resolution

- Ordinary agents omit `seller`; this service defaults to `emino.nuri.eth`.
- Advanced callers may supply an explicitly enabled seller, but it is not part of the normal purchase flow.
- ENSIP-10/CCIP-read resolves the current Ethereum address.
- The address is pinned when the 402 offer is created.
- A later ENS change cannot redirect an existing operation.
- Inspect resolution: https://nuri.com/api/x402/resolve/emino.nuri.eth

## Idempotency and failures

Nuri derives `operation_id` deterministically from the normalized postcard request when the agent omits it; advanced callers may override it. The x402 payment-identifier remains required in the payment payload. A stored SHA-256 fingerprint binds the operation to the complete postcard request without persisting recipient PII. Process-local plus filesystem locks serialize the complete provider-send and settlement flow across overlapping deployment containers. Retries cannot send or settle twice. If hard settlement fails after thanks.io accepted the order, Nuri immediately requests cancellation. A broadcast-but-unconfirmed `settlement_pending` transaction is not canceled; it enters reconciliation with the transaction hash retained.

## Privacy

Recipient details go to thanks.io for fulfillment but are not persisted in Nuri's order ledger. Public status exposes only the seller, payout address, provider order ID, charged amount, payment transaction, delivery counters and error counts.

## 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.

## Machine-readable sources

- Catalog: https://nuri.com/api/x402
- OpenAPI: https://nuri.com/openapi.json
- Agentic commerce: https://nuri.com/.well-known/agentic-commerce.json
- This document as Markdown: https://nuri.com/docs/x402-username-marketplace/index.md

## 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.

The Nuri-owned discovery surfaces are live. External Bazaar listing is not yet claimed because no funded client has echoed and settled the Bazaar extension through the facilitator.

## 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.