> ## 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.

# Tokens API Routes

> Every wallet-authenticated Tokens API v1 route - path, params, constraints, and example.

Tokens API routes proxy [Tokens API](https://tokens.xyz) v1 with a server-side API key held by the gateway. Clients authenticate per request with a Solana wallet signature using the x402 **sign-in-with-x** (SIWX) extension.

## Conventions

All Tokens routes share the same shape:

* **Access mode:** `siwx` (auth-only - **no USDC is transferred**)
* **Price:** `$0.00` per request
* **Auth networks:** `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (mainnet), `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (devnet)
* **Auth header:** `SIGN-IN-WITH-X`
* **Challenge expiry:** `300 seconds`
* **Rate limit:** `30 rpm` across the shared upstream API key (configurable)
* **Success body:** `{ ok: true, provider: "tokens", surface: "tokens", method, result }`
* **Path base:** every route is mounted under `/v1/x402/tokens/...`

Enumerated values (validated by the gateway before upstream):

| Parameter                    | Allowed values                                                                               |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| `include`                    | `profile`, `risk`, `ohlcv`, `markets`                                                        |
| `interval` / `ohlcvInterval` | `1m`, `5m`, `15m`, `1H`, `4H`, `1D`, `1W`                                                    |
| `kind`                       | `native, wrapped, bridged, etf, yield, leveraged, basket, lst, stablecoin, tokenized_equity` |
| `liquidityTier`              | `tier1`, `tier2`, `tier3`                                                                    |
| `trustTier`                  | `tier1`, `tier2`, `tier3`, `experimental`                                                    |
| `list` (curated)             | `all, majors, lsts, currencies, rwas, etfs, metals, stocks`                                  |
| `groupBy`                    | `asset`, `mint`                                                                              |
| `variantsMode`               | `all`                                                                                        |

## Index

| #  | Route                                                 | Method | Notes                                    |
| -- | ----------------------------------------------------- | ------ | ---------------------------------------- |
| 1  | `/v1/x402/tokens/health`                              | `GET`  | Upstream health probe                    |
| 2  | `/v1/x402/tokens/assets/search`                       | `GET`  | Search canonical assets                  |
| 3  | `/v1/x402/tokens/assets/resolve`                      | `GET`  | Resolve alias/mint to canonical asset id |
| 4  | `/v1/x402/tokens/assets/curated`                      | `GET`  | Curated asset lists                      |
| 5  | `/v1/x402/tokens/assets/market-snapshots`             | `POST` | Batch market snapshots by mint           |
| 6  | `/v1/x402/tokens/assets/variant-markets`              | `GET`  | Batch cached per-mint variant markets    |
| 7  | `/v1/x402/tokens/assets/risk-summary`                 | `GET`  | Per-mint risk summary                    |
| 8  | `/v1/x402/tokens/assets/:assetId`                     | `GET`  | Asset detail with optional includes      |
| 9  | `/v1/x402/tokens/assets/:assetId/variants`            | `GET`  | Variants list                            |
| 10 | `/v1/x402/tokens/assets/:assetId/variant-top-markets` | `GET`  | Top market per variant                   |
| 11 | `/v1/x402/tokens/assets/:assetId/variant-market`      | `GET`  | Single variant market snapshot           |
| 12 | `/v1/x402/tokens/assets/:assetId/markets`             | `GET`  | DEX markets for one mint                 |
| 13 | `/v1/x402/tokens/assets/:assetId/ohlcv`               | `GET`  | OHLCV candles                            |
| 14 | `/v1/x402/tokens/assets/:assetId/price-chart`         | `GET`  | Canonical price candles                  |
| 15 | `/v1/x402/tokens/assets/:assetId/profile`             | `GET`  | Cached external profile                  |
| 16 | `/v1/x402/tokens/assets/:assetId/tickers`             | `GET`  | Exchange tickers                         |
| 17 | `/v1/x402/tokens/assets/:assetId/risk-summary`        | `GET`  | Simple risk summary                      |
| 18 | `/v1/x402/tokens/assets/:assetId/risk-details`        | `GET`  | Detailed risk summary                    |
| 19 | `/v1/x402/tokens/assets/:assetId/description`         | `GET`  | Cached per-mint description              |

***

## 1. `health`

`GET /v1/x402/tokens/health`

Proxy the Tokens API v1 health check. Takes no parameters.

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/health" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 2. `search`

`GET /v1/x402/tokens/assets/search`

Search canonical assets.

| Param      | Type    | Required | Notes                           |
| ---------- | ------- | -------- | ------------------------------- |
| `q`        | string  | yes      | Search text, non-empty.         |
| `limit`    | integer | no       | `1..50`.                        |
| `category` | string  | no       | Optional asset category filter. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/search?q=solana&limit=5" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 3. `resolve`

`GET /v1/x402/tokens/assets/resolve`

Resolve an alias or Solana mint to a canonical Tokens asset id. Provide **exactly one** of `ref` or `mint`.

| Param  | Type   | Required | Notes                        |
| ------ | ------ | -------- | ---------------------------- |
| `ref`  | string | one of   | Canonical asset id or alias. |
| `mint` | string | one of   | Solana mint address.         |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/resolve?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 4. `curated`

`GET /v1/x402/tokens/assets/curated`

Return a curated asset list.

| Param     | Type   | Required | Notes                                                               |
| --------- | ------ | -------- | ------------------------------------------------------------------- |
| `list`    | string | yes      | One of `all, majors, lsts, currencies, rwas, etfs, metals, stocks`. |
| `groupBy` | string | no       | `asset` or `mint`.                                                  |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/curated?list=majors&groupBy=asset" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 5. `marketSnapshots`

`POST /v1/x402/tokens/assets/market-snapshots`

Batch lookup of cached market snapshots for Solana mints.

**Body**

```json theme={null}
{
  "mints": ["<mint1>", "<mint2>"],
  "addresses": ["<mint3>"]
}
```

| Field       | Type      | Required | Notes              |
| ----------- | --------- | -------- | ------------------ |
| `mints`     | string\[] | one of   | Non-empty strings. |
| `addresses` | string\[] | one of   | Non-empty strings. |

At least one of `mints` or `addresses` must be provided. Combined size is capped at **250** ids per request.

**Example**

```bash theme={null}
curl -X POST "https://gateway.Ryvo.network/v1/x402/tokens/assets/market-snapshots" \
  -H "Content-Type: application/json" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>" \
  -d '{"mints":["So11111111111111111111111111111111111111112","EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"]}'
```

***

## 6. `variantMarkets`

`GET /v1/x402/tokens/assets/variant-markets`

Batch lookup cached per-mint variant market snapshots. Combined cap of **50** ids per request.

| Param       | Type            | Required | Notes                                  |
| ----------- | --------------- | -------- | -------------------------------------- |
| `mints`     | comma-separated | one of   | Comma-separated Solana mint addresses. |
| `addresses` | comma-separated | one of   | Comma-separated Solana mint addresses. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/variant-markets?mints=So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 7. `riskSummaryByMint`

`GET /v1/x402/tokens/assets/risk-summary`

Quick market-based risk summary for a Solana mint.

| Param  | Type   | Required | Notes                |
| ------ | ------ | -------- | -------------------- |
| `mint` | string | yes      | Solana mint address. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/risk-summary?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 8. `assetDetail`

`GET /v1/x402/tokens/assets/:assetId`

Fetch a canonical Tokens asset and optional include blocks.

**Path params**

| Param     | Type   | Required | Notes                                                       |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `assetId` | string | yes      | Canonical asset id (`solana`) or singleton `solana-<mint>`. |

**Query params**

| Param           | Type    | Notes                                                    |
| --------------- | ------- | -------------------------------------------------------- |
| `include`       | string  | Comma-separated: any of `profile, risk, ohlcv, markets`. |
| `mint`          | string  | Variant mint used for include computations.              |
| `variantsMode`  | string  | `all`.                                                   |
| `ohlcvInterval` | string  | One of the documented intervals.                         |
| `ohlcvFrom`     | integer | Unix seconds, `>= 0`.                                    |
| `ohlcvTo`       | integer | Unix seconds, `>= ohlcvFrom`.                            |
| `marketsOffset` | integer | `0..10000`.                                              |
| `marketsLimit`  | integer | `1..50`.                                                 |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana?include=profile,risk&marketsLimit=5" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 9. `variants`

`GET /v1/x402/tokens/assets/:assetId/variants`

List canonical asset variants, optionally filtered.

**Path params**

| Param     | Type   | Required | Notes               |
| --------- | ------ | -------- | ------------------- |
| `assetId` | string | yes      | Canonical asset id. |

**Query params**

| Param           | Type   | Notes                                      |
| --------------- | ------ | ------------------------------------------ |
| `kind`          | string | One of the allowed variant kinds.          |
| `liquidityTier` | string | `tier1`, `tier2`, `tier3`.                 |
| `trustTier`     | string | `tier1`, `tier2`, `tier3`, `experimental`. |
| `mint`          | string | Specific variant mint.                     |
| `variantsMode`  | string | `all`.                                     |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/ethereum/variants?liquidityTier=tier1" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 10. `variantTopMarkets`

`GET /v1/x402/tokens/assets/:assetId/variant-top-markets`

Top DEX market for each asset variant.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param          | Type    | Notes       |
| -------------- | ------- | ----------- |
| `offset`       | integer | `0..10000`. |
| `limit`        | integer | `1..100`.   |
| `variantsMode` | string  | `all`.      |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/variant-top-markets?limit=10" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 11. `variantMarket`

`GET /v1/x402/tokens/assets/:assetId/variant-market`

Cached variant-market snapshot for a single mint of the asset.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param  | Type   | Notes                           |
| ------ | ------ | ------------------------------- |
| `mint` | string | Optional specific variant mint. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/variant-market?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 12. `markets`

`GET /v1/x402/tokens/assets/:assetId/markets`

List cached DEX markets for one mint of the asset.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param    | Type    | Notes                   |
| -------- | ------- | ----------------------- |
| `mint`   | string  | Optional specific mint. |
| `offset` | integer | `0..10000`.             |
| `limit`  | integer | `1..50`.                |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/markets?limit=10" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 13. `ohlcv`

`GET /v1/x402/tokens/assets/:assetId/ohlcv`

OHLCV candles for a specific mint variant.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param      | Type    | Notes                                 |
| ---------- | ------- | ------------------------------------- |
| `mint`     | string  | Optional specific variant mint.       |
| `interval` | string  | One of `1m, 5m, 15m, 1H, 4H, 1D, 1W`. |
| `from`     | integer | Unix seconds, `>= 0`.                 |
| `to`       | integer | Unix seconds, `>= from`.              |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/ohlcv?interval=1D" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 14. `priceChart`

`GET /v1/x402/tokens/assets/:assetId/price-chart`

Canonical price candles, with mint fallback when needed.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param      | Type    | Notes                                 |
| ---------- | ------- | ------------------------------------- |
| `mint`     | string  | Optional specific mint.               |
| `interval` | string  | One of `1m, 5m, 15m, 1H, 4H, 1D, 1W`. |
| `from`     | integer | Unix seconds, `>= 0`.                 |
| `to`       | integer | Unix seconds, `>= from`.              |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/price-chart?interval=1D" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 15. `profile`

`GET /v1/x402/tokens/assets/:assetId/profile`

Cached external profile and market stats.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

No query parameters.

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/profile" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 16. `tickers`

`GET /v1/x402/tokens/assets/:assetId/tickers`

Cached exchange tickers for the canonical asset.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param    | Type    | Notes                |
| -------- | ------- | -------------------- |
| `offset` | integer | `0..10000`.          |
| `limit`  | integer | `1..50`.             |
| `order`  | string  | Optional order hint. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/tickers?limit=10" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 17. `riskSummary`

`GET /v1/x402/tokens/assets/:assetId/risk-summary`

Simple risk summary for a mint of the asset.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param  | Type   | Notes                   |
| ------ | ------ | ----------------------- |
| `mint` | string | Optional specific mint. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/risk-summary?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 18. `riskDetails`

`GET /v1/x402/tokens/assets/:assetId/risk-details`

Detailed risk summary for a mint of the asset.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param  | Type   | Notes                   |
| ------ | ------ | ----------------------- |
| `mint` | string | Optional specific mint. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/risk-details?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## 19. `description`

`GET /v1/x402/tokens/assets/:assetId/description`

Cached per-mint description summary.

**Path params**

| Param     | Type   | Required |
| --------- | ------ | -------- |
| `assetId` | string | yes      |

**Query params**

| Param  | Type   | Notes                   |
| ------ | ------ | ----------------------- |
| `mint` | string | Optional specific mint. |

**Example**

```bash theme={null}
curl "https://gateway.Ryvo.network/v1/x402/tokens/assets/solana/description?mint=So11111111111111111111111111111111111111112" \
  -H "SIGN-IN-WITH-X: <base64 SIWX payload>"
```

***

## Not proxied

`GET /v1/whoami` is a first-party Clerk-session endpoint in the Tokens API, not an API-key endpoint. It is intentionally excluded from the gateway surface.

## See also

* [Solana RPC routes](/gateway/routes/solana-rpc)
* [Solana DAS routes](/gateway/routes/solana-das)
* [Access modes](/gateway/access-modes)
* [Rate limiting & guardrails](/gateway/rate-limiting)
* [Integration guide](/gateway/integration-guide)