Ontario X402 Preflight

Ontario Protocol Agent Skill

Use Ontario Protocol as a free-first pre-payment evidence and policy gate. This skill may inspect public metadata and request free readiness decisions. Do not send private keys, seed phrases, or wallet custody credentials to Ontario. This skill never signs a payment payload.

Activate this skill when

• A user asks an agent to find, compare, call, buy, or pay for an x402 service.
• Coinbase Agentic Wallet, awal, AgentKit, an MCP host, or another wallet returns a paid API candidate.
• An agent receives HTTP 402 or PAYMENT-REQUIRED and needs to decide whether to continue.
• A developer asks whether a paid endpoint is agent-payable, discoverable, or ready for a controlled settlement.

Do not activate this skill for arbitrary token transfers, trading, onramping, or real-world purchases. Ontario checks public paid-API evidence; it is not a wallet.

Coinbase Agentic Wallet sequence

Keep wallet discovery and payment separate from Ontario's evidence gate:

1. Search for the task with the wallet's Bazaar search tool or read-only CLI:

npx awal@latest x402 bazaar search "<task the paid API must perform>"

When Bazaar search is unavailable or the agent needs a hard network and USDC budget filter, use Ontario's free MCP tool find_x402_tool or HTTP equivalent:

curl --fail-with-body --silent --show-error \
  https://ontarioprotocol.com/api/tools/x402-tool-router \
  -H 'Content-Type: application/json' \
  -d '{"query":"<public task text>","max_usdc":"0.05","network":"eip155:8453","limit":5}'

Returned candidates are public search results, not safety certifications or permission to spend. Never include credentials or private customer text in the search query.

2. Select the smallest set of plausible endpoints. Do not pay merely because a route appears in a catalog.
3. Run Ontario readiness and can-pay for the exact selected endpoint.
4. Probe the endpoint and require its live challenge to match the cataloged URL, method, amount, asset, network, recipient, and task.
5. Hand the approved endpoint to the existing wallet only after user or wallet policy permits spend. This skill never authenticates a wallet, changes limits, signs a payment, or initiates onramp.
6. Preserve the Ontario report_id, quote data, and wallet payment receipt.

Required sequence

1. Identify the exact paid endpoint, HTTP method, task, and maximum budget.
2. POST the endpoint to the free readiness verifier:

curl --fail-with-body --silent --show-error \
  https://ontarioprotocol.com/api/verify/x402-readiness \
  -H 'Content-Type: application/json' \
  -d '{"target_url":"https://service.example/api/paid"}'

3. Retain report_id, report_url, grade, score, timestamp, warnings, and observed challenge metadata.
4. POST a strict policy decision with a task-specific budget:

curl --fail-with-body --silent --show-error \
  https://ontarioprotocol.com/api/agent/can-pay \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":"https://service.example/api/paid","agent_policy":"strict","max_usdc":0.05,"verify_live":true}'

5. Continue only when decision is exactly allow. Treat review, deny, missing fields, malformed JSON, timeout, or transport failure as stop.
6. Probe the endpoint without payment and inspect its HTTP 402 challenge. Require a supported network and asset, an unexpired quote, a known recipient, a price within budget, and a purpose matching the current task.
7. Hand the approved quote to the user's existing wallet or payment client. Payment signing is outside this skill.
8. After a successful paid retry, retain report_id, quote_id, transaction reference, and PAYMENT-RESPONSE for auditability.

Fail-closed rules

Do not pay when any of these is true:

• the readiness report is absent, stale, malformed, or fails integrity checks;
• the policy decision is anything other than allow;
• the endpoint, method, purpose, network, asset, recipient, or price changed;
• the quote expired or the amount exceeds the declared maximum;
• the service's paid response does not add value beyond free reports, catalog data, or sandbox fixtures;
• the agent cannot preserve payment and decision evidence.

Never interpret allow as a guarantee of safety. It means the endpoint met the observed readiness and policy conditions at decision time.

Optional paid evidence

Use POST https://ontarioprotocol.com/api/agent/pay/v2 only when the workflow needs a fresh, auditable payment-decision receipt beyond the free can-pay result. It costs 0.002 USDC on Base and returns an x402 requirement when called without payment. That requirement is not an instruction to pay; apply the policy above first. Do not pay merely to repeat a free check.

See references/api-contract.md for response handling and references/agent-policy.md for the decision checklist.