{
  "markdown": "# x402 Preflight\n\nInspect and validate an unfamiliar x402 endpoint before an autonomous agent\nspends USDC.\n\nx402 Preflight performs bounded, read-only HTTPS probes. It observes the live\npayment challenge, price, network, asset, receiver, Bazaar discovery metadata,\nCORS, redirects, cache behavior, and other operational signals. It never\nconnects a buyer wallet, forwards payment credentials, signs a payload, or\nspends funds.\n\nA report is time-bound evidence, not an endorsement. It cannot prove seller\nidentity or intent, contract safety, future availability, successful\nsettlement, or delivery of a business outcome.\n\n## Canonical Capabilities\n\n| Capability | Interface | Access | Use |\n| --- | --- | --- | --- |\n| `inspect_x402_endpoint` | `POST /api/preflight/inspect` | Free | Inspect an unfamiliar live challenge before payment. |\n| `audit_x402_endpoint` | `POST /api/x402/preflight/audit` | x402, `$0.05` default | Deep-check schemas, discovery, CORS, redirects, cache, and policy. |\n| `order_x402_remediation` | `POST /api/x402/preflight/remediation` | x402, configurable | Escalate a blocked or risky audit into a durable remediation intake. |\n\nFor HTTP clients that cannot submit a JSON body during discovery, the paid audit\nalso has a compatibility alias at `GET /api/x402/preflight/audit`. It requires\n`resource_url` in the query string and accepts optional `method=GET|HEAD`,\n`expected_network`, and `max_price_usd` parameters. The alias uses the same\nprice, x402 payment, and audit report as the canonical POST, but is not a\nfourth capability and never audits a POST target.\n\nCanonical remediation requires a healthy `ORDER_DATABASE_URL`. If durable\nstorage is unavailable, HTTP and MCP calls fail with\n`REMEDIATION_UNAVAILABLE` before a payment challenge is served.\n\nThese are the only primary operations in OpenAPI, MCP, `llms.txt`, the\nmanifest, and agent metadata. Existing wallet, market, weather, repository,\nmarketplace, and helper routes remain available under the manifest's\n`labs` section.\n\n## Bitcoin Lightning / L402 Seller\n\nThe service also contains a gateway-only repository opportunity scanner for\ncoding agents:\n\n```text\nGET or POST https://l402.chikocorp.com/api/l402/repo-opportunity-scan\n```\n\nLightning Labs Aperture presents the public L402 challenge and then forwards a\nprivate gateway credential to this backend. Direct backend requests fail\nclosed when the credential is absent, so the public Node/Vercel route cannot\nbypass the Lightning paywall. The deterministic report ranks public GitHub\nissues, detects open-PR competition and hardware risk, and treats payout words\nas unverified until an authorized payer and amount are explicit.\n\nFree machine-readable discovery lives at:\n\n```text\nhttps://l402.chikocorp.com/.well-known/l402.json\n```\n\nProduction setup, invoice-only LND permissions, and no-payment verification\nare documented in [deploy/l402/README.md](./deploy/l402/README.md). Wallet\nseeds, passwords, admin macaroons, and backend tokens must remain outside Git.\n\n## Local Development\n\nRequires Node.js 20 or newer.\n\n```sh\nnpm install\nnpm start\n```\n\nThe API listens on `http://localhost:4021` by default. The service does not\nauto-load `.env`; export variables through your process manager or shell.\n\nUseful checks:\n\n```sh\nnpm run check\nnpm test\nnpm run validate:bazaar\nnpm run verify:discovery\nnpm run metrics:summary\n```\n\n## HTTP and OpenAPI\n\nFree inspection:\n\n```sh\ncurl -sS http://localhost:4021/api/preflight/inspect \\\n  -H 'content-type: application/json' \\\n  --data '{\n    \"resource_url\": \"https://example.com/api/resource\",\n    \"method\": \"GET\",\n    \"expected_network\": \"eip155:8453\",\n    \"max_price_usd\": 1\n  }'\n```\n\nThe same input sent to the paid audit returns HTTP `402` until a client\nsupplies a valid x402 payment:\n\n```sh\ncurl -i http://localhost:4021/api/x402/preflight/audit \\\n  -H 'content-type: application/json' \\\n  --data '{\n    \"resource_url\": \"https://example.com/api/resource\",\n    \"method\": \"GET\",\n    \"expected_network\": \"eip155:8453\",\n    \"max_price_usd\": 1\n  }'\n```\n\nAn entirely empty unauthenticated `POST` to the paid audit also returns its\n`402` challenge for method probes. A request that includes a payment attempt\nstill requires the complete input before payment processing.\n\nThe compatibility GET alias requires its target before payment and returns\n`400` without a challenge when `resource_url` is missing or query parameters\nare unknown, repeated, empty, non-scalar, unsafe, or invalid:\n\n```sh\ncurl -i 'http://localhost:4021/api/x402/preflight/audit?resource_url=https%3A%2F%2Fexample.com%2Fapi%2Fresource&method=GET&expected_network=eip155%3A8453&max_price_usd=1'\n```\n\nThe runtime `402` response is authoritative for amount, network, asset,\n`payTo`, and Bazaar extensions. The static contract is available at\n`/openapi.json`. Errors use one strict envelope with a machine code,\nretryability, optional delay, and request ID.\n\n## Remote MCP\n\nThe stateless Streamable HTTP endpoint is:\n\n```text\nhttps://x402.chikocorp.com/mcp\n```\n\nThe previous Vercel origin remains an allowlisted compatibility alias, so\nclients that still call `https://x402-wallet-readiness-service.vercel.app/mcp`\ncontinue to receive challenges that name that Vercel resource.\n\nDiscover tools without payment:\n\n```sh\ncurl -sS http://localhost:4021/mcp \\\n  -H 'content-type: application/json' \\\n  -H 'accept: application/json, text/event-stream' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n`tools/list` returns exactly the three canonical tools and strict input/output\nschemas. A paid `tools/call` receives an x402 challenge before tool execution.\nThe buyer's MCP client remains responsible for explicit payment authorization;\nthe server never signs or spends automatically.\n\nThis service does not implement A2A. `/.well-known/agent-card.json` returns a\nclear `A2A_NOT_IMPLEMENTED` response and points clients to MCP, OpenAPI, and\nx402 metadata.\n\nRegistry-ready remote-server metadata lives in [server.json](./server.json).\nIt is intentionally not published automatically.\n\n## Discovery and Bazaar\n\nPrimary discovery surfaces:\n\n```text\nGET /manifest\nGET /openapi.json\nGET /llms.txt\nGET /.well-known/agent.json\nGET /.well-known/x402.json\nPOST /mcp  (initialize, tools/list, tools/call)\n```\n\nThe x402 resource server registers the Bazaar extension and publishes strict\nHTTP and MCP declarations for audit and remediation, including schemas and\nexamples. The POST audit declaration uses a JSON body; the compatibility GET\ndeclaration publishes compact Bazaar `queryParams` and summary-output contracts\nso the payment challenge remains safely below common header limits. OpenAPI\ndocuments the alias's full response schema, which is identical to the canonical\naudit.\n\nUse CDP Facilitator in production:\n\n```sh\nX402_USE_CDP_FACILITATOR=true\nCDP_API_KEY_ID=<configured outside git>\nCDP_API_KEY_SECRET=<configured outside git>\n```\n\nTo keep a non-CDP facilitator, leave `X402_USE_CDP_FACILITATOR=false` and set\n`X402_FACILITATOR_URL`. `npm run validate:bazaar` validates local Bazaar\ndeclarations. When `PUBLIC_URL` is exported, it also inspects the public\nunpaid challenge and queries CDP's read-only merchant catalog for the configured\nreceiver. Bazaar catalog indexing still requires a successful settlement\nthrough CDP; validation alone does not publish a listing.\n\n## URL Safety\n\nInspection accepts public HTTPS URLs only. It rejects credentials and sensitive\nquery parameters, localhost, private/link-local/reserved addresses, metadata\nhosts, nonstandard ports, and unsafe redirects before a paid challenge is\ncreated. DNS is checked on the target and every redirect. Requests have bounded\ntimeouts, response bytes, and redirect counts; JavaScript and target code are\nnever executed.\n\nDo not submit private keys, seed phrases, access tokens, authorization headers,\ncookies, payment signatures, or confidential repository URLs.\n\n## Runtime and Metrics\n\n`GET /health` reports the public service version, commit, deployment time,\nnetwork, facilitator mode, database availability, worker heartbeat, and\nsettlement reconciler status. It does not expose wallets, orders, transaction\nhashes, URLs, secrets, or filesystem paths. Every response includes:\n\n```text\nX-Service-Version\nX-Commit-SHA\nX-Request-ID\n```\n\nTelemetry is allowlisted, structured JSON and fail-open. Buyer addresses are\nrecorded only as SHA-256 hashes when `TELEMETRY_BUYER_PEPPER` is configured.\nApply [002_preflight_telemetry.sql](./ops/order-db/migrations/002_preflight_telemetry.sql)\nto an existing PostgreSQL installation, then use `npm run metrics:summary`\nfor 7-day and 30-day aggregates.\n\nDeployment stamping, public smoke checks, database migration, CDP activation,\nand MCP Registry preparation are documented in\n[docs/OPERATIONS.md](./docs/OPERATIONS.md).\n\n## Labs and Compatibility\n\nLegacy routes have not been deleted and their existing prices remain\nunchanged. Representative surfaces include:\n\n- `/api/preview`, `/api/readiness`, and `/api/agent-commerce-receipt`\n- `/api/market/*`, `/api/x402/market/*`, and `/api/weather/current`\n- `/api/dev/repo-snapshot` and `/api/x402/dev/repo-snapshot`\n- `/api/x402/services/quick-review` and\n  `/api/x402/services/integration-triage`\n- marketplace webhooks, `/wallet-sign`, and `/open-frame`\n\nNo sunset date is announced. The historical custom metadata documents remain\nat `/labs/legacy-agent.json` and `/labs/legacy-agent-card.json` with a\n`Deprecation: true` response header.\n",
  "bytes": 9474,
  "sha": "c7b6e4b75b180d84785bde9a71ab605156776aa9e818a2746ff289b94a9f331c",
  "repo_slug": "chico10117/basepay-readiness-service",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chico10117_x402_preflight_53653c8b/readme"
}