> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryvo.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement

> How paid requests settle on Solana, and why you are never charged for a failed call.

Every paid call through the gateway settles in **USDC on Solana mainnet** through a standard [x402](https://x402.org) facilitator. Tokens API routes do not settle on-chain; they authenticate with a wallet signature and no funds move.

This page describes what settlement means for you as a client. If you want the mechanics of the x402 wire format, see [Access modes](/gateway/access-modes) and the [Payment headers reference](/gateway/reference/payment-headers).

## The guarantee

**You pay only for successful calls.**

For every paid request, the gateway performs the following sequence:

1. **Verify** - the `PAYMENT-SIGNATURE` you attach is checked against the advertised price, network, and recipient.
2. **Call upstream** - the gateway forwards your validated request to the underlying provider (Alchemy, Helius).
3. **Settle on success** - only if the upstream returned a successful response, the gateway submits your pre-signed transfer on-chain.

If anything in steps 1 or 2 fails, verification error, provider outage, malformed upstream reply, the gateway discards the payment authorization and no USDC moves. You can retry safely; each attempt produces a new single-use payment.

## What you see back

On a successful paid request, the gateway returns the upstream's JSON response plus an `X-PAYMENT-RESPONSE` header containing a proof of settlement:

```json theme={null}
{
  "success": true,
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "transaction": "<Solana transaction hash>",
  "payer": "<your wallet pubkey>",
  "settledAt": "2026-04-18T11:32:00Z"
}
```

The `transaction` field is a standard Solana signature you can look up in any explorer. It is the canonical record that this call was paid for.

SIWX (Tokens API) responses never include this header because nothing is settled on-chain.

## Non-custodial by design

* The gateway **never holds your funds**. Your `PAYMENT-SIGNATURE` is a transfer you signed directly from your own wallet; settlement submits that transfer as-is.
* The gateway never requests or stores your private keys.
* The gateway cannot settle a payment for more than the price advertised in the original `402` challenge.

## Replay protection

Each `PAYMENT-SIGNATURE` authorizes exactly one call. Submitting the same payment twice returns `400 Bad Request`, the second call is not settled. This is enforced before the upstream call, so there is no way a paid request can be charged twice.

## See also

* [How it works](/gateway/how-it-works)
* [Access modes](/gateway/access-modes)
* [Pricing](/gateway/pricing)
* [Payment headers reference](/gateway/reference/payment-headers)