Start here

From rumour to a working paid route

1. Read what the machine economy is and how 402 works.
2. Run the Hello x402 reference in this repository — unpaid 402, paid JSON. It is tested.
3. Put a schema on the door. Additional properties closed unless you mean to be open.
4. Discoverability: live 402 must match OpenAPI / well-known. More metadata is not automatically better.
5. Price above variable cost. Measure repeat payers, not first-call vanity.

Build your first x402 API

{
  "id": "hello-x402",
  "title": "Hello x402",
  "architecture": "Unpaid POST → HTTP 402 challenge. Paid retry → deterministic JSON transform. No private keys in the reference.",
  "setup": "Copy handleHelloX402 into any HTTP server. Point payTo at your receive address. Use a real facilitator only in production.",
  "schemas": {
    "input": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        }
      },
      "required": [
        "text"
      ],
      "additionalProperties": false
    },
    "output": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string"
        },
        "length": {
          "type": "integer"
        }
      },
      "required": [
        "text",
        "length"
      ]
    }
  },
  "paymentFlow": "discover schema → POST → 402 → pay exact USDC on Base → retry → 200 JSON",
  "expectedCost": "$0.001 per call at 1000 atomic USDC, plus network fees paid by the buyer wallet — not by this reference.",
  "security": [
    "Do not put a seller private key in the server.",
    "Do not paste a seed phrase into an agent prompt.",
    "Validate input before settlement in production paid paths."
  ],
  "testing": "node --test test/zfinia-learn.test.mjs",
  "discovery": {
    "wellKnown": false,
    "educational": true,
    "notFoundryProductionRoute": true
  },
  "deployment": "Educational snippet. Do not deploy this as a Foundry production product without the full receive-only gates."
}