# Market endpoints

SRC-20 market data from the StampDEX API: token lists, price history, trades, fee rates, the deployment resolution routes, and the source map on every row.

> Source: bitcoinuniverseio/stampdex (private application source), market controller and market aggregation util. Applicable release continuous deployment, verify with GET /api/version. Last verified 2026-09-01. Chain bitcoin/mainnet.

Base path: `/api/v1/market`.

## Routes

| Method | Path | Returns |
| --- | --- | --- |
| GET | `/overview` | Market-wide summary |
| GET | `/tokens` | The token index: the stamp index merged with the StampDEX order book |
| GET | `/tokens/priced` | A faster feed of tokens with live exchange prices |
| GET | `/tokens/:tick` | One token in detail |
| GET | `/tokens/:tick/context` | Token context including the order book |
| GET | `/tokens/:tick/prices` | Recorded price history |
| GET | `/tokens/:tick/trades` | Recent trades |
| GET | `/tokens/:tick/activity` | Per-token activity |
| POST | `/tokens/prices` | Prices for a list of tickers in one call |
| GET | `/deployments/:tick` | Every deployment claiming a ticker |
| GET | `/deployments/tx/:deployTx` | The deployment behind a transaction |
| GET | `/fees` | Recommended Bitcoin fee rates |

## Parameters

| Parameter | Where | Range |
| --- | --- | --- |
| `page` | `/tokens`, `/tokens/priced`, `/tokens/:tick/activity` | 1 upwards |
| `limit` | `/tokens` | Up to 500. 0 means every row |
| `limit` | `/tokens/priced` | Up to 500 |
| `limit` | `/tokens/:tick/prices` | Up to 500, default 200 |
| `limit` | `/tokens/:tick/trades` | Default 50 |

Tickers are uppercase. The API upcases what you send. An unknown ticker returns an
empty result, not an error.

## Example

```bash frame=none
curl "https://stamp.api.bitcoinuniverse.io/api/v1/market/tokens/KEVIN"
```

## Reading the numbers

- Every row carries a `sources` object naming the origin of each figure:
  `stampchain`, `stampdex`, or `none`. See
  [Data provenance](/docs-stampdex/concepts/data-provenance/).
- Every row carries `deploy_tx`, `deploy_block`, `deploy_time`, and `creator`.
  `sources.identity` reads `stampchain` when a source reported one and `none` when none
  did. `deploy_tx` is null in that case, and the ticker is never used in its place.
- `mint_progress` is minted supply against max supply, as a percentage.
- `total_minted` and `max_supply` are strings, so a very large supply does not lose
  precision.
- A null or absent value means the source had no answer. It is never replaced with 0.
- A market cap above 21,000,000 BTC is reported as unknown rather than repeated.
- Listing prices come from real signed listings. A stored listing whose unit price
  contradicts its total is left off the book rather than shown at a wrong price.

## Deployment resolution

```bash frame=none
curl "https://stamp.api.bitcoinuniverse.io/api/v1/market/deployments/KEVIN"
```

The response carries `resolution` with one of `single`, `ambiguous`, `unknown`, or
`unavailable`, plus `source`, `source_available`, `observed_at`, and a `deployments`
array. Each entry names `tick`, `deploy_tx`, `deploy_block`, `deploy_time`, `creator`,
`max_supply`, and `mint_limit`.

Going the other way:

```bash frame=none
curl "https://stamp.api.bitcoinuniverse.io/api/v1/market/deployments/tx/23765f9bc6b87e078b1f93ed213f90b9004998336575f726e46f34ddbea5e5f3"
```

That returns `found` and the deployment. A value that is not 64 hex characters returns
HTTP 400 rather than being searched for.

## Fee rates

```bash frame=none
curl "https://stamp.api.bitcoinuniverse.io/api/v1/market/fees"
```

Five tiers: fastest, half hour, hour, economy, and minimum. If any tier is missing or is
not a number, the whole response is rejected with HTTP 502. Partial fee data is never
served. See [Fees](/docs-stampdex/reference/fees/).

## Common failures

| Status | Meaning |
| --- | --- |
| 400 | A malformed parameter, such as a transaction id that is not 64 hex characters |
| 429 | Over the rate limit. See [Rate limits](/docs-stampdex/api/rate-limits/) |
| 502 | The upstream node returned fee estimates that did not validate |

## Related

- [Market data](/docs-stampdex/concepts/market-data/)
- [Deployment identity](/docs-stampdex/concepts/deployment-identity/)