x402 seller recipe

What this recipe gives you

Your buyers can check a delivery against explicit acceptance criteria. Spoolis returns the accepted and rejected units, per-unit earned value, a signed Outcome Receipt, and a hosted URL they can share.

Before you start

What you sell must be checkable as rows, files, fields, or another explicit result. If simple delivery is already enough to determine payment, this recipe is probably unnecessary. See when to use Spoolis.

Step 1: define acceptance criteria

Write down the checks before the buyer receives the product. For a company dataset, you might require one row per purchased company and require every row to include company_id, domain, and employee_count. A row that lacks a required field is rejected with a reason, while complete rows can still be accepted.

Keep the criteria concrete enough for fixed code to evaluate. Avoid criteria such as “high quality” unless the agreement also names who decides what that means.

Step 2: point buyers at verification

The canonical one-call verification route is POST /api/v1/verify. For direct x402 pay-per-verification, send the same request body to POST /api/v1/verify/x402, read the payment requirement, sign it, and retry the same request with the payment signature. The request below represents three delivered items as three dataset rows. Its unit.total_units matches the row count, and each accepted row earns 100 cents of the 300-cent maximum.

{
  "conditions": [
    {
      "description": "Every delivered company row includes company_id, domain, and employee_count",
      "deterministic_check": {
        "checker": "completeness",
        "required_fields": ["company_id", "domain", "employee_count"]
      }
    }
  ],
  "max_amount_cents": 300,
  "unit": { "total_units": 3, "unit_amount_cents": 100 },
  "evidence": {
    "type": "dataset",
    "rows": [
      { "company_id": "co_001", "domain": "example.com", "employee_count": 42 },
      { "company_id": "co_002", "domain": "example.org", "employee_count": 18 },
      { "company_id": "co_003", "domain": "example.net", "employee_count": null }
    ],
    "provenance": "api_response"
  },
  "settlement": "external",
  "idempotency_key": "delivery-order-4831"
}

Text evidence plus a unit count is refused by the MCP tool. On the raw API it settles batch-only, so it cannot award partial per-item value. Dataset rows support partial acceptance, unit-level rejection reasons, and per-unit earned value. Keep an expected field present with a null value when it is missing.

Use the endpoint response contract in the API reference, and send buyers to pricing for current verification pricing.

Step 3: use the Outcome Receipt

The buyer receives a signed receipt in receipt and its public receipt_url. Hosted receipts use https://spoolis.com/r/<id>. The URL gives the buyer, seller, marketplace, or another system a shared artifact to inspect and link.

Link the hosted receipt from your order record or delivery message. In your listing, explain that eligible deliveries include a signed Outcome Receipt and are checked against the criteria you publish.

What to put in your listing

Use only claims that match the product you actually deliver and the checks you configured. Approved phrases:

• Outcome-verified
• Includes a signed Outcome Receipt
• Delivery checked against explicit acceptance criteria