Ontario Protocol.
Listing conversion

Checklist: Get Your x402 Service Into /discover

Ontario discovery is not a marketing form. It is a verification-backed catalog: listings appear immediately in /listings, but /discover is filtered to endpoints whose stored readiness report grades ready (plus score thresholds). Use this checklist to remove ambiguity before an agent pays.

Commands

1) Run the free verifier (creates a public report) 
curl -X POST https://ontarioprotocol.com/api/verify/x402-readiness \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/api/paid-endpoint"}'
2) Probe the paid listing endpoint (expect HTTP 402, no signature yet) 
curl -i -X POST https://ontarioprotocol.com/api/x402/list-service \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Service","description":"Paid endpoint","endpoint":"https://example.com/api/paid","method":"POST","price_usdc":"0.01","network":"base","owner_url":"https://example.com"}'

Pass the discovery gate (grade + score)

Your listing can exist without being discoverable. Ontario’s strict catalog defaults should exclude endpoints with weak readiness evidence so agents do not pay based on marketing copy.

Evidence: Ontario renders /listings (includes pending), and /discover (machine catalog) is positioned as verification-backed with grade/score filters for agent payment readiness.

Fix: Aim for grade=ready and a high score by fixing scanner warnings, then re-run /api/verify/x402-readiness to store a fresh report.

Return an x402-readable HTTP 402 challenge

An endpoint that returns HTTP 402 but omits machine-readable requirements forces agents to guess. Agents need the accepted scheme, network, asset, amount, resource, and expiry before constructing a payment payload.

Evidence: Ontario’s readiness scanner explicitly checks 402 challenge behavior and penalizes common gaps; the verifier UX instructs agents to probe a paid endpoint and expect a 402 before paying.

Fix: Ensure your 402 response includes an x402-compatible body (and/or decodable PAYMENT-REQUIRED header) with a complete accepts entry that matches the endpoint you are gating.

Keep /.well-known/x402.json consistent with the live challenge

Agents and crawlers reconcile what your manifest claims against what your endpoint enforces. Mismatches (network, asset, price, method) cause policy denial or failed payment retries.

Evidence: Ontario verifies /.well-known/x402.json presence/shape and compares manifest metadata against observed endpoint behavior as part of the readiness score.

Fix: Treat the manifest as a contract with your agents: update it when price/network/method/schema changes and keep generated_at fresh.

Publish OpenAPI (so agents can validate inputs/outputs)

Paid endpoints without schemas are high-risk for agents: they cannot validate request shape, estimate cost, or enforce safe output parsing.

Evidence: Ontario’s readiness checks include OpenAPI availability; reports and service profiles link to evidence surfaces rather than relying on prose claims.

Fix: Expose an OpenAPI document that covers the paid endpoint (path, method, requestBody, responses) and keep it aligned with production behavior.

Make your evidence linkable (report + badge)

Discovery should be evidence-first: a badge is only meaningful if it links to a public report with score, warnings, and integrity verification.

Evidence: Ontario publishes public report URLs, report integrity endpoints, and SVG badges for readiness reports; /reports and /services pages are crawlable evidence surfaces.

Fix: After you reach grade=ready, embed the Ontario badge (or link to the report URL) in your docs/readme and keep re-verifying on a schedule.

Submit via /api/x402/list-service (paid) after you’re ready

The paid submission fee is an anti-spam gate, not a substitute for readiness. Agents should still run preflight checks (and budgets) before spending.

Evidence: /listings describes the paid submission path and the separation between pending listings vs discovery inclusion; /verify explicitly avoids wallet signatures and settlement attempts.

Fix: Run /verify first, then submit the endpoint metadata to /api/x402/list-service with an x402 client that signs a payment payload. Do not collect user private keys; keep signing client-side.

Sources

Run the readiness checker