# Ontario X402 Preflight

> Verify x402 endpoint readiness and apply a fail-closed payment policy before an autonomous agent pays. Use when a user or agent asks to find, compare, call, or pay for an x402 or HTTP 402 service; when Coinbase Agentic Wallet, awal, MCP, AgentKit, or another wallet discovers a paid API; or when payment challenge, price, network, asset, report freshness, and evidence must be checked before spend.

- Skill: `thetechdevpro/ontario-x402-preflight` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add thetechdevpro/ontario-x402-preflight`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thetechdevpro/ontario-x402-preflight/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: TheTechDevPro (https://skillmd.com/u/thetechdevpro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thetechdevpro/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.