# GET /v1/solana/payment/verify

Did this settled Solana payment deliver the expected amount to the expected recipient?

## Purpose

Reads the transaction `signature` once at `finalized` and compares what the recipient received with what you expected, returning a derived `verdict` and nothing else about the accounts. The answer is never an error when the transaction is absent: `not_found` (the node served no transaction, and the signature has no status or a `finalized` one) and `not_final` (it is not finalized yet) are verdicts with a 200, and neither is definitive: ask again later. The other verdicts are `failed` (the transaction errored), `unverifiable` (a token balance entry for the mint names no owner, so who received it cannot be told), `reference_mismatch` (only with `reference`), `wrong_sender` (only with `source`), `paid`, `underpaid`, `wrong_asset` (the recipient's balance rose in another mint or in SOL) and `wrong_recipient`. The first verdict that matches, in that order, is the one returned.

| Verdict | What settles it | Definitive |
|---|---|---|
| `not_found` | the node served no transaction, and the signature has no status or a `finalized` one | not definitive: ask again later |
| `not_final` | the transaction is not finalized yet | not definitive: ask again later |
| `failed` | the transaction errored | definitive |
| `unverifiable` | a token balance entry for the mint names no owner, so who received it cannot be told | definitive |
| `reference_mismatch` | `reference` is given and is not among the account keys | definitive |
| `wrong_sender` | `source` is given and did not sign the transaction | definitive |
| `paid` | the recipient received at least `amount` | definitive |
| `underpaid` | the recipient received more than 0 and less than `amount` | definitive |
| `wrong_asset` | the recipient's balance rose in another mint or in SOL | definitive |
| `wrong_recipient` | none of the above applies | definitive |

`received` is what the recipient's own balance gained, so a Token-2022 transfer fee is already deducted and a token account closed in the same transaction counts its whole balance as a negative delta. `excess` is what was received above `amount` on a `paid` verdict. When the mint does not appear in the transaction's token balances its decimals are unknown and nothing is guessed: `expected.raw` and `received.ui` are then `null`. `valuation` is an informative EUR and USD reference value given only on a `paid` or `underpaid` verdict for a registry stablecoin when an ECB rate on or before the payment date is stored; otherwise it is `null`. The value is an informative reference, not a tax figure. Source: ECB statistics. A finalized transaction never changes, so its answer is fresh for 86400 seconds and served stale for up to 604800; `not_found` and `not_final` are fresh for 4 seconds and served stale for up to 30. If the upstream read fails, an answer cached within its stale window is served instead of a 503. 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 a payment has been submitted: to confirm from the chain that the recipient received the mint and amount you expected, including the Token-2022 fee case.

## When not to use

Before sending a transfer (use `/v1/solana/transfer-readiness`), or to list a wallet's transfers or balances (none are returned).

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `signature` | query | yes | Transaction signature of the payment to verify. | A base58 string that decodes to exactly 64 bytes (a Solana transaction signature); anything else is a 400 | `B7yABUkY4RudiDfoax94mfqVv2YuNJ4AVsg7LjdFT9Qm8bScsw3PoB2LxpuUqzCkiniKQJ9AKXfSfWaw1kWYFaF` |
| `recipient` | query | yes | Wallet the payment had to reach (not its token account). | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400 | `GEJySUi6LjHwQWKD2BDg3TiGKwhKmBU7JJTjZfk1RD54` |
| `mint` | query | yes | `SOL` for native SOL, or the mint address of the SPL Token or Token-2022 token the payment had to deliver. | `SOL` or a base58 string that decodes to exactly 32 bytes (a solana public key); anything else is a 400 | `SOL` |
| `amount` | query | yes | Amount the payment had to deliver, in UI units (not lamports or raw units). | Positive decimal string (no exponent); at most 9 decimals for SOL, checked before any read, and at most the mint's decimals for a token, checked after the read when the mint appears in the transaction's token balances | `0.02` |
| `reference` | query | no | Reference key the payment had to carry among its account keys (the Solana Pay marker); without it the reference is not compared. | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400 | `A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd` |
| `source` | query | no | Wallet the payment had to be signed by; without it the sender is not compared. | A base58 string that decodes to exactly 32 bytes (a Solana public key); anything else is a 400 | `6LY1JzAFVZsP2a2xKrtU6znQMQ5h4i7tocWdgrkZzkzF` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/solana/payment/verify?signature=B7yABUkY4RudiDfoax94mfqVv2YuNJ4AVsg7LjdFT9Qm8bScsw3PoB2LxpuUqzCkiniKQJ9AKXfSfWaw1kWYFaF&recipient=GEJySUi6LjHwQWKD2BDg3TiGKwhKmBU7JJTjZfk1RD54&mint=SOL&amount=0.02"
```

## Response example (200)

```json
{
  "verdict": "paid",
  "expected": {
    "raw": "20000000",
    "ui": "0.02"
  },
  "received": {
    "raw": "20000000",
    "ui": "0.02"
  },
  "excess": "0",
  "slot": 466203592,
  "block_time": "2026-11-06T18:04:52.000Z",
  "valuation": null,
  "meta": {
    "slot": 466203592,
    "commitment": "finalized",
    "as_of": "2026-11-11T20:19:07.997Z",
    "age_seconds": 0,
    "cache": "miss",
    "stale": false
  }
}
```

## Errors

- 400 [invalid-parameters](https://api.criptonlabs.com/errors/invalid-parameters.md)
- 400 [bad-request](https://api.criptonlabs.com/errors/bad-request.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_payment_verify` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).
