# GET /v1/solana/x402/preflight

Can this payer settle this x402 payment requirement right now?

## Purpose

Takes one x402 v2 `exact` requirement as an SVM server states it (`asset`, the mint the payment moves, `amount` in that mint's base units and `pay_to`) plus the `payer` wallet, and answers one `verdict`: `block` on any blocker, `warn` with warnings only, else `ok`. The facilitator is the fee payer (`extra.feePayer`) and pays only the network fee, so `insufficient_sol_for_fees` and `source_below_rent_exempt` never apply here (the embedded `readiness` may still list them). A `pay_to` without a token account for the mint is the blocker `pay_to_ata_missing`: the payment is a `TransferChecked` to the existing associated token account of `pay_to` and `asset`, and the fee payer may not appear in any instruction, so nothing in that transaction can create it; an address already occupied by another program's account is the different blocker `destination_ata_occupied`, carried as it is. `readiness` is what `/v1/solana/transfer-readiness` answers for the same payer, recipient, mint and amount, without its `meta`, so both routes can be compared field by field; its `amount` is the UI rendering of the atomic `amount` once the mint's decimals are read. Each readiness blocker becomes the blocker `payer_<code>` and each readiness warning the warning `payer_<code>`. A `pay_to` that is a token account, mint, multisig, program, stake or vote account is the blocker `pay_to_not_wallet`, and one owned by another program the warning `pay_to_program_owned`; `destination_not_wallet`, `destination_program_owned` and `destination_ata_occupied` are then not repeated as `payer_*`, while the embedded `readiness` still lists them. An off-curve wallet and an address with no account are not `pay_to_not_wallet`; whether either has the token account is the separate `pay_to_ata_missing` check. An `asset` that is not the canonical stablecoin of the registry gives the warning `asset_not_canonical`. `pay_to` must differ from `payer`: the same address is a 400 naming `pay_to`, and nothing is read. `pay_to` is read in the same batch as the readiness accounts, so the check makes exactly the readiness reads and no others.

| Code | What it states | Blocks or warns |
|---|---|---|
| `pay_to_not_wallet` | `pay_to` is a token account, mint, multisig, program, stake or vote account | blocks |
| `pay_to_ata_missing` | `pay_to` has no token account for the mint, and nothing in the transaction can create it | blocks |
| `destination_ata_occupied` | the address of the associated token account is already occupied by another program's account | blocks |
| `pay_to_program_owned` | `pay_to` is owned by another program | warns |
| `asset_not_canonical` | `asset` is not the canonical stablecoin of the registry | warns |
| `payer_*` | every applicable payer readiness blocker or reason appears with the prefix `payer_` (`payer_<code>`), and each readiness warning appears as the warning `payer_<code>`; the codes are those of `/v1/solana/transfer-readiness` | blocks or warns, as the readiness code does |

Every figure is read at finalized commitment, so it can lag the tip of the chain by about 13 seconds; `meta.slot` is the lowest context slot of the reads behind the answer.

## When to use

After an x402 server answered 402 with a Solana `exact` requirement: to check, before signing, that this payer can settle that exact requirement to that recipient now.

## When not to use

For a transfer that is not an x402 requirement (use `/v1/solana/transfer-readiness`), or once the payment has settled (use `/v1/solana/payment/verify`).

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `asset` | query | yes | Mint of the requirement: the token the payment moves. | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400; `SOL` is not accepted, because an x402 SVM `exact` payment is always a token transfer | `2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo` |
| `amount` | query | yes | Amount the requirement asks for, in the mint's base units (not UI units), exactly as the requirement states it. | Whole number of base units (digits only), greater than 0 and at most 18446744073709551615 (the u64 maximum) | `1000000` |
| `pay_to` | query | yes | Wallet the requirement pays (not its token account). | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400 | `29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2` |
| `payer` | query | yes | Wallet that would pay. | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400 | `6vk7icY2FzdMTzMGE4aNRSzovanAmS7xsv9uHwj4YuzY` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/solana/x402/preflight?asset=2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo&amount=1000000&pay_to=29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2&payer=6vk7icY2FzdMTzMGE4aNRSzovanAmS7xsv9uHwj4YuzY"
```

## Response example (200)

```json
{
  "verdict": "block",
  "blockers": [
    "pay_to_ata_missing",
    "payer_insufficient_balance"
  ],
  "warnings": [],
  "readiness": {
    "source": "6vk7icY2FzdMTzMGE4aNRSzovanAmS7xsv9uHwj4YuzY",
    "destination": "29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2",
    "mint": "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
    "amount": "1",
    "amount_raw": "1000000",
    "decimals": 6,
    "token_program": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
    "ready": false,
    "blockers": [
      "insufficient_balance"
    ],
    "warnings": [],
    "requires_ata_creation": true,
    "ata_creation_lamports": "1600200",
    "transfer_fee": "0",
    "net_amount": "1000000",
    "destination_kind": "not_found",
    "ui_multiplier": null,
    "interest_rate_bps": null,
    "transfer_fee_next": null
  },
  "meta": {
    "slot": 456943158,
    "commitment": "finalized",
    "as_of": "2026-10-14T12:00:03.000Z",
    "age_seconds": 0,
    "cache": "miss",
    "stale": false
  }
}
```

## Errors

- 400 [invalid-parameters](https://api.criptonlabs.com/errors/invalid-parameters.md)
- 404 [solana-mint-not-found](https://api.criptonlabs.com/errors/solana-mint-not-found.md)
- 429 [rate-limited](https://api.criptonlabs.com/errors/rate-limited.md)
- 503 [upstream-unavailable](https://api.criptonlabs.com/errors/upstream-unavailable.md)

## Caching

Fresh for 4 seconds; on upstream failure the last good value is served for up to 30 seconds (`meta.stale` is `true`), then the service answers 503. See the [freshness guide](https://api.criptonlabs.com/docs/guides/freshness.md).

## Rate limit

Tier `expensive`. See the [rate-limits guide](https://api.criptonlabs.com/docs/guides/rate-limits.md).

## MCP tool

The MCP tool `solana_x402_preflight` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).
