# Solana Index x402 Agent Guide

This guide describes how an AI agent should access paid x402 endpoints on Solana Index.

## Base URL

- Production: `https://solanaindex.top`

## Paid x402 Routes

- `GET /api/v1/x402/solana/slot`
- `GET /api/v1/x402/solana/slot-timestamp/:slot`
- `GET /api/v1/x402/solana/token-balance/:address/:token/:slot`

## Price and Asset

- Price: `0.01` USDC per request
- Network: `base`
- Asset (USDC): `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`

## Required Payment Flow

1. Send request without payment header.
2. Receive `402` with `accepts[]` requirement payload.
3. Create x402 payment proof for one accepted requirement.
4. Retry request with:
   - `X-PAYMENT: <base64-encoded signed payment payload>`
5. Read response:
   - `200`: request succeeded
   - `202`: payment authorization accepted but settlement tx hash not ready yet
   - `402`: missing/invalid/replayed or otherwise rejected payment proof
   - `409`: payment replay detected by server-side tx-hash ledger

## Headers

- Request payment header:
  - `X-PAYMENT`
- Optional response settlement header:
  - `X-PAYMENT-RESPONSE`

## Example 1: Current Slot (`/api/v1/x402/solana/slot`)

### Unpaid Request

```bash
curl --request GET \
  --url https://solanaindex.top/api/v1/x402/solana/slot
```

### `402 payment_required` Example

```json
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://solanaindex.top/api/v1/x402/solana/slot",
      "description": "GET /api/v1/x402/solana/slot",
      "mimeType": "application/json",
      "payTo": "0x23459a89eAc054bdAC1c13eB5cCb39F42574C26a",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
```

### Paid Retry

```bash
curl --request GET \
  --url https://solanaindex.top/api/v1/x402/solana/slot \
  --header "X-PAYMENT: <BASE64_SIGNED_PAYMENT_PAYLOAD>"
```

### `200` Success Example

```json
{
  "slot": 421609847,
  "timestamp": "2026-05-23T09:41:53.000Z",
  "source": "rpc",
  "fetchedAt": "2026-05-23T09:41:53.309Z"
}
```

## Example 2: Slot Timestamp (`/api/v1/x402/solana/slot-timestamp/:slot`)

### Paid Request

```bash
curl --request GET \
  --url https://solanaindex.top/api/v1/x402/solana/slot-timestamp/413754398 \
  --header "X-PAYMENT: <BASE64_SIGNED_PAYMENT_PAYLOAD>"
```

### `200` Success Example

```json
{
  "slot": 413754398,
  "timestamp": "2026-05-18T14:36:21.794Z",
  "source": "cache",
  "fetchedAt": "2026-05-19T00:00:00.000Z"
}
```

## Example 3: Token Balance (`/api/v1/x402/solana/token-balance/:address/:token/:slot`)

### Paid Request

```bash
curl --request GET \
  --url "https://solanaindex.top/api/v1/x402/solana/token-balance/EqMawiRYydw2JRsgnMaqeJupohztDz1dJkF1BvPJCLwJ/BcJgLEF5viPPgRVYCcLyR59vDM3UqyuU8jUJT1BVZVF9/413754398" \
  --header "X-PAYMENT: <BASE64_SIGNED_PAYMENT_PAYLOAD>"
```

### `200` Success Example

```json
{
  "balance": "5398.924408859",
  "balanceRaw": "5398924408859",
  "decimals": 9,
  "slot": 413754398,
  "address": "EqMawiRYydw2JRsgnMaqeJupohztDz1dJkF1BvPJCLwJ",
  "token": "BcJgLEF5viPPgRVYCcLyR59vDM3UqyuU8jUJT1BVZVF9",
  "tokenAccount": "92eYjjRE9TsgLFuti7KW3C9pE6B1x7hVabAyBKKCGrcW",
  "source": "cache",
  "fetchedAt": "2026-05-18T14:36:21.794Z"
}
```

## Pending Settlement and Replay Responses

### `202 pending_onchain` Example

```json
{
  "status": "pending_onchain",
  "message": "The payment authorization was accepted but has not been settled on-chain yet.",
  "x402Version": 1,
  "settlement": {},
  "requirement": {}
}
```

### `409 payment_replay` Example

```json
{
  "error": "payment_replay",
  "message": "This payment proof has already been used.",
  "txHash": "0x..."
}
```

### Replay may also return `402`

Depending on facilitator behavior, replayed payment payloads can be rejected during verification (for example nonce already used) and return `402` instead of `409`.

## Idempotency and Replay

- Do not reuse the same payment proof for multiple requests.
- Generate a new payment proof per request URL.

## Notes for Agents

- For historical slot queries, use exact integer slot values.