# Agent Preflight APIs

Use Purchase Shortlist when an agent needs to choose an x402 API under price,
network, or method constraints. It searches Coinbase Bazaar, live-checks up to
three unpaid challenges, rejects stale or uninvocable offers, and returns a
purchase-ready request skeleton without paying any target.

Use Endpoint Preflight immediately before an agent pays a specific unfamiliar
x402 endpoint. It checks the live unpaid challenge for price, network, payee,
resource binding, timeout, and Bazaar metadata. It never pays the target.

No signup or API key is required. Invalid or unsafe inputs fail before payment.

## Purchase Shortlist

- Paid shortlist: POST https://email-preflight-api.vercel.app/api/x402-shortlist
- Price: USD 0.005 USDC on Base through x402 v2
- Free static sample: GET https://email-preflight-api.vercel.app/api/x402-shortlist/sample

Input:

```json
{
  "need": "current weather for a city",
  "maxPriceUsd": 0.01,
  "network": "eip155:8453",
  "method": "GET"
}
```

`need` is required. The price, network, and method filters are optional.
Read `recommendation.request` for the exact request skeleton. Treat
`partial`, `partial_no_match`, and `search_unavailable` honestly; a
recommendation is a technical match, not proof of merchant identity, safety,
settlement, or paid-response quality.

## Endpoint Preflight

- Paid check: POST https://email-preflight-api.vercel.app/api/x402-preflight
- Price: USD 0.003 USDC on Base through x402 v2
- Free static sample: GET https://email-preflight-api.vercel.app/api/x402-preflight/sample
- OpenAPI: https://email-preflight-api.vercel.app/openapi.json
- x402 descriptor: https://email-preflight-api.vercel.app/.well-known/x402

Input:

```json
{
  "url": "https://merchant.example/api/paid-resource",
  "method": "POST",
  "expected": {
    "network": "eip155:8453",
    "payTo": "0x1111111111111111111111111111111111111111",
    "maxAmountUsd": 0.01
  }
}
```

`url` is required. `method` may be GET, HEAD, or POST and defaults to
POST. Every `expected` field is optional. Unknown fields and unsafe targets
are rejected free before payment.

## Call sequence

1. Read the relevant free sample and OpenAPI contract.
2. POST a valid JSON request to the selected paid endpoint.
3. Handle its x402 v2 payment challenge and retry with payment authorization.
4. For Purchase Shortlist, use `recommendation`, `alternates`, and
   `disqualifications` to choose whether to buy from a target.
5. For Endpoint Preflight, use `summary.compatible`, `findings`, and the
   decoded `challenge` to decide whether to proceed with the target purchase.

## Safety and limits

- Public HTTPS port 443 targets only; private and special-use destinations are
  rejected.
- Redirects are not followed and response bodies are not read.
- No caller headers, credentials, cookies, or payment authorization are sent to
  the target.
- POST probes send the fixed JSON object `{}`; callers cannot supply a body.
- An unpaid probe cannot prove settlement, merchant identity, paid-response
  quality, or future behavior.