Tokens API Routes

Tokens API routes proxy Tokens API 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

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

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

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

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

{
  "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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Introduction

Concepts

Routes

Integrate

Agentic

Reference

Conventions

Index

1. `health`

2. `search`

3. `resolve`

4. `curated`

5. `marketSnapshots`

6. `variantMarkets`

7. `riskSummaryByMint`

8. `assetDetail`

9. `variants`

10. `variantTopMarkets`

11. `variantMarket`

12. `markets`

13. `ohlcv`

14. `priceChart`

15. `profile`

16. `tickers`

17. `riskSummary`

18. `riskDetails`

19. `description`

Not proxied

See also

Introduction

Concepts

Routes

Integrate

Agentic

Reference

Documentation Index

​Conventions

​Index

​1. health

​2. search

​3. resolve

​4. curated

​5. marketSnapshots

​6. variantMarkets

​7. riskSummaryByMint

​8. assetDetail

​9. variants

​10. variantTopMarkets

​11. variantMarket

​12. markets

​13. ohlcv

​14. priceChart

​15. profile

​16. tickers

​17. riskSummary

​18. riskDetails

​19. description

​Not proxied

​See also

Conventions

Index

1. `health`

2. `search`

3. `resolve`

4. `curated`

5. `marketSnapshots`

6. `variantMarkets`

7. `riskSummaryByMint`

8. `assetDetail`

9. `variants`

10. `variantTopMarkets`

11. `variantMarket`

12. `markets`

13. `ohlcv`

14. `priceChart`

15. `profile`

16. `tickers`

17. `riskSummary`

18. `riskDetails`

19. `description`

Not proxied

See also