**Base URL:** `https://api.baseline.markets`

All REST endpoints are versioned under `/v1/`. Address parameters must be EIP-55 checksummed.

Integration endpoints that expose indexed on-chain data are chain-scoped. Use the `:chain` path segment to select the network:

| Chain       | Alias            | Chain ID |
| :---------- | :--------------- | :------- |
| `ethereum`  | `mainnet`        | `1`      |
| `base`      | —                | `8453`   |
| `hyperevm`  | `hyperliquid`    | `999`    |
| `robinhood` | `robinhoodchain` | `4663`   |

Legacy unscoped integration routes are still served as Ethereum mainnet, but chain-scoped routes are preferred.

***

## Protocol metrics

### GET /v1/protocol/metrics

Returns current protocol-level reserve metrics grouped by chain and reserve token, plus the Baseline staking metric for \$B. Values are raw integer token units; use the returned `decimals` field to decimalize balances.

<ApiExample url="https://api.baseline.markets/v1/protocol/metrics" />

**Response**

```json
{
  "reserveMetrics": [
    {
      "chainId": "1",
      "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "symbol": "WETH",
      "decimals": 18,
      "reserveLiquidity": "712116589552028176816",
      "totalDebt": "14788752752346013575496",
      "totalCreatorFees": "5663969771441968974",
      "totalProtocolFees": "3977595860797789422",
      "totalStakingFees": "0",
      "totalVolume": "761102995753535272538"
    }
  ],
  "stakingMetrics": [
    {
      "chainId": "1",
      "tokenAddress": "0x9fDbDE76236998Dc2836FE67A9954eDE456A1D63",
      "symbol": "B",
      "decimals": 18,
      "totalStaked": "29569970092404356096317215"
    }
  ]
}
```

| Field                                | Type     | Description                                                                       |
| :----------------------------------- | :------- | :-------------------------------------------------------------------------------- |
| `reserveMetrics[].chainId`           | `string` | EVM chain ID                                                                      |
| `reserveMetrics[].tokenAddress`      | `string` | Reserve token contract address on the chain                                       |
| `reserveMetrics[].symbol`            | `string` | Reserve token symbol                                                              |
| `reserveMetrics[].decimals`          | `number` | Reserve token decimals                                                            |
| `reserveMetrics[].reserveLiquidity`  | `string` | Total reserve liquidity across indexed Baseline pools, in raw reserve token units |
| `reserveMetrics[].totalDebt`         | `string` | Total outstanding debt across indexed Baseline pools, in raw reserve token units  |
| `reserveMetrics[].totalCreatorFees`  | `string` | Total creator fees accrued, in raw reserve token units                            |
| `reserveMetrics[].totalProtocolFees` | `string` | Total protocol fees accrued, in raw reserve token units                           |
| `reserveMetrics[].totalStakingFees`  | `string` | Total staking fees accrued, in raw reserve token units                            |
| `reserveMetrics[].totalVolume`       | `string` | Total swap volume, in raw reserve token units                                     |
| `stakingMetrics[].chainId`           | `string` | EVM chain ID                                                                      |
| `stakingMetrics[].tokenAddress`      | `string` | Staked \$B token contract address on the chain                                    |
| `stakingMetrics[].symbol`            | `string` | Token symbol                                                                      |
| `stakingMetrics[].decimals`          | `number` | Token decimals                                                                    |
| `stakingMetrics[].totalStaked`       | `string` | Total \$B amount staked in Baseline, in raw token units                           |

***

## DexScreener adapter

Implements the [DexScreener Adapter Spec v1.1](https://dexscreener.notion.site/DEX-Screener-Adapter-Specs-cc1223cdf6e74a7799599106b65dcd0e). These endpoints are queried directly by DexScreener to index Baseline pools.

### GET /v1/dexscreener/:chain/latest-block

Returns the latest indexed block for a chain. DexScreener polls this continuously to determine where to resume indexing.

<ApiExample url="https://api.baseline.markets/v1/dexscreener/ethereum/latest-block" />

**Response**

```json
{
  "block": {
    "blockNumber": 24922675,
    "blockTimestamp": 1776706931
  }
}
```

| Field                  | Type     | Description                            |
| :--------------------- | :------- | :------------------------------------- |
| `block.blockNumber`    | `number` | Latest indexed block number            |
| `block.blockTimestamp` | `number` | Unix timestamp (seconds) of that block |

***

### GET /v1/dexscreener/:chain/asset

Returns token metadata for a given contract address on a chain.

**Query parameters**

| Parameter | Type     | Required | Description                        |
| :-------- | :------- | :------- | :--------------------------------- |
| `id`      | `string` | Yes      | Checksummed token contract address |

<ApiExample url="https://api.baseline.markets/v1/dexscreener/ethereum/asset?id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B" />

**Response**

```json
{
  "asset": {
    "id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "name": "Based Liquidity Token",
    "symbol": "BLT",
    "decimals": 18,
    "totalSupply": "72000000",
    "circulatingSupply": "29569970.092404356096317215"
  }
}
```

| Field                     | Type     | Description                                             |
| :------------------------ | :------- | :------------------------------------------------------ |
| `asset.id`                | `string` | Contract address                                        |
| `asset.name`              | `string` | Token name                                              |
| `asset.symbol`            | `string` | Token symbol                                            |
| `asset.decimals`          | `number` | Token decimals (also used to decimalize supply fields)  |
| `asset.totalSupply`       | `string` | Decimalized total supply (omitted if unavailable)       |
| `asset.circulatingSupply` | `string` | Decimalized circulating supply (omitted if unavailable) |

**Errors**

| Status | Body                                                                             | Cause                                     |
| :----- | :------------------------------------------------------------------------------- | :---------------------------------------- |
| `400`  | `{ error: [{ message: "Invalid input: expected string, received undefined" }] }` | Missing or invalid `id` parameter         |
| `404`  | `{ error: "Asset not found" }`                                                   | Address not in the indexed token registry |

***

### GET /v1/dexscreener/:chain/pair

Returns pool metadata for a given btoken contract address on a chain.

**Query parameters**

| Parameter | Type     | Required | Description                         |
| :-------- | :------- | :------- | :---------------------------------- |
| `id`      | `string` | Yes      | Checksummed btoken contract address |

<ApiExample url="https://api.baseline.markets/v1/dexscreener/ethereum/pair?id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B" />

**Response**

```json
{
  "pair": {
    "id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "dexKey": "baseline",
    "asset0Id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "asset1Id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "createdAtBlockNumber": 24921292,
    "createdAtBlockTimestamp": 1776690287,
    "createdAtTxnId": "0x7576a097a1680a8ec8a595212572b49e0d9cc8d64cfdcd891f5bc2bce2aa2178",
    "creator": "0xB2A9f3886134e5F6A19a1A87bD62343FE2685c64"
  }
}
```

| Field                          | Type     | Description                                   |
| :----------------------------- | :------- | :-------------------------------------------- |
| `pair.id`                      | `string` | btoken contract address (the pair identifier) |
| `pair.dexKey`                  | `string` | Always `"baseline"`                           |
| `pair.asset0Id`                | `string` | btoken address                                |
| `pair.asset1Id`                | `string` | Reserve token address (WETH on mainnet)       |
| `pair.createdAtBlockNumber`    | `number` | Pool deploy block                             |
| `pair.createdAtBlockTimestamp` | `number` | Pool deploy Unix timestamp                    |
| `pair.createdAtTxnId`          | `string` | Pool deploy transaction hash                  |
| `pair.creator`                 | `string` | Address that deployed the pool                |

**Errors**

| Status | Body                          | Cause                          |
| :----- | :---------------------------- | :----------------------------- |
| `404`  | `{ error: "Pair not found" }` | No pool found for this address |

***

### GET /v1/dexscreener/:chain/events

Returns swap events within an inclusive block range for a chain. DexScreener uses this to index historical and live trades.

**Query parameters**

| Parameter   | Type     | Required | Description             |
| :---------- | :------- | :------- | :---------------------- |
| `fromBlock` | `number` | Yes      | Start block (inclusive) |
| `toBlock`   | `number` | Yes      | End block (inclusive)   |

Maximum range: 2000 blocks per request.

<ApiExample url="https://api.baseline.markets/v1/dexscreener/ethereum/events?fromBlock=24921292&toBlock=24922675" />

**Response**

```json
{
  "events": [
    {
      "block": { "blockNumber": 24921350, "blockTimestamp": 1776691000 },
      "eventType": "swap",
      "txnId": "0x7576a097a1680a8ec8a595212572b49e0d9cc8d64cfdcd891f5bc2bce2aa2178",
      "txnIndex": 4,
      "eventIndex": 0,
      "maker": "0xB2A9f3886134e5F6A19a1A87bD62343FE2685c64",
      "pairId": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
      "asset1In": "0.5",
      "asset0Out": "966424.684",
      "priceNative": "0.00000063",
      "reserves": {
        "asset0": "29569970.09",
        "asset1": "0.61"
      }
    }
  ]
}
```

Each event is a swap. `asset0` is always the btoken; `asset1` is always the reserve token.

| Field             | Type     | Description                                    |
| :---------------- | :------- | :--------------------------------------------- |
| `eventType`       | `"swap"` | Always `"swap"`                                |
| `txnId`           | `string` | Transaction hash                               |
| `txnIndex`        | `number` | Transaction order within block                 |
| `eventIndex`      | `number` | Event order within transaction                 |
| `maker`           | `string` | Wallet that submitted the transaction          |
| `pairId`          | `string` | btoken address                                 |
| `asset1In`        | `string` | Reserve amount in (buy)                        |
| `asset0Out`       | `string` | btoken amount out (buy)                        |
| `asset0In`        | `string` | btoken amount in (sell)                        |
| `asset1Out`       | `string` | Reserve amount out (sell)                      |
| `priceNative`     | `string` | Price of asset0 quoted in asset1 (decimalized) |
| `reserves.asset0` | `string` | Post-swap btoken pool balance                  |
| `reserves.asset1` | `string` | Post-swap reserve pool balance                 |

All amounts are decimalized (`amount / 10 ** decimals`).

**Errors**

| Status | Body                                                 | Cause                               |
| :----- | :--------------------------------------------------- | :---------------------------------- |
| `400`  | `{ error: "Block range exceeds max range of 2000" }` | Range greater than 2000 blocks      |
| `400`  | `{ error: [{ message: "..." }] }`                    | Missing or invalid query parameters |

***

## CoinGecko and GeckoTerminal adapter

CoinGecko-related HTTP surfaces on Baseline: a **GeckoTerminal-compatible on-chain index** (`latest-block`, `asset`, `pair`, `events`) and a **CoinGecko decentralized spot exchange** feed (`tickers`, `orderbook`, `historical_trades`). Chain-scoped routes use the prefix `/v1/coingecko/:chain/`.

### GET /v1/coingecko/:chain/latest-block

Returns the latest indexed block for a chain. This value should stay in sync with `/events`: it is the highest block for which event data is available for range queries.

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/latest-block" />

**Response**

```json
{
  "block": {
    "blockNumber": 24922675,
    "blockTimestamp": 1776706931
  }
}
```

| Field                  | Type     | Description                            |
| :--------------------- | :------- | :------------------------------------- |
| `block.blockNumber`    | `number` | Latest indexed block number            |
| `block.blockTimestamp` | `number` | Unix timestamp (seconds) of that block |

***

### GET /v1/coingecko/:chain/asset

Returns token metadata for a given contract address on a chain.

**Query parameters**

| Parameter | Type     | Required | Description                        |
| :-------- | :------- | :------- | :--------------------------------- |
| `id`      | `string` | Yes      | Checksummed token contract address |

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/asset?id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B" />

**Response**

```json
{
  "asset": {
    "id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "name": "Based Liquidity Token",
    "symbol": "BLT",
    "decimals": 18,
    "totalSupply": "72000000",
    "circulatingSupply": "29569970.092404356096317215"
  }
}
```

| Field                     | Type     | Description                                             |
| :------------------------ | :------- | :------------------------------------------------------ |
| `asset.id`                | `string` | Contract address                                        |
| `asset.name`              | `string` | Token name                                              |
| `asset.symbol`            | `string` | Token symbol                                            |
| `asset.decimals`          | `number` | Token decimals (also used to decimalize supply fields)  |
| `asset.totalSupply`       | `string` | Decimalized total supply (omitted if unavailable)       |
| `asset.circulatingSupply` | `string` | Decimalized circulating supply (omitted if unavailable) |

**Errors**

| Status | Body                                                                             | Cause                                     |
| :----- | :------------------------------------------------------------------------------- | :---------------------------------------- |
| `400`  | `{ error: [{ message: "Invalid input: expected string, received undefined" }] }` | Missing or invalid `id` parameter         |
| `404`  | `{ error: "Asset not found" }`                                                   | Address not in the indexed token registry |

***

### GET /v1/coingecko/:chain/pair

Returns pool metadata for a given btoken contract address on a chain.

**Query parameters**

| Parameter | Type     | Required | Description                         |
| :-------- | :------- | :------- | :---------------------------------- |
| `id`      | `string` | Yes      | Checksummed btoken contract address |

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/pair?id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B" />

**Response**

```json
{
  "pair": {
    "id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "dexKey": "baseline",
    "asset0Id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "asset1Id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "createdAtBlockNumber": 24921292,
    "createdAtBlockTimestamp": 1776690287,
    "createdAtTxnId": "0x7576a097a1680a8ec8a595212572b49e0d9cc8d64cfdcd891f5bc2bce2aa2178",
    "creator": "0xB2A9f3886134e5F6A19a1A87bD62343FE2685c64"
  }
}
```

| Field                          | Type     | Description                                   |
| :----------------------------- | :------- | :-------------------------------------------- |
| `pair.id`                      | `string` | btoken contract address (the pair identifier) |
| `pair.dexKey`                  | `string` | Always `"baseline"`                           |
| `pair.asset0Id`                | `string` | btoken address                                |
| `pair.asset1Id`                | `string` | Reserve token address (WETH on mainnet)       |
| `pair.createdAtBlockNumber`    | `number` | Pool deploy block                             |
| `pair.createdAtBlockTimestamp` | `number` | Pool deploy Unix timestamp                    |
| `pair.createdAtTxnId`          | `string` | Pool deploy transaction hash                  |
| `pair.creator`                 | `string` | Address that deployed the pool                |

**Errors**

| Status | Body                          | Cause                          |
| :----- | :---------------------------- | :----------------------------- |
| `404`  | `{ error: "Pair not found" }` | No pool found for this address |

***

### GET /v1/coingecko/:chain/events

Returns swap events within an inclusive block range for a chain.

**Query parameters**

| Parameter   | Type     | Required | Description             |
| :---------- | :------- | :------- | :---------------------- |
| `fromBlock` | `number` | Yes      | Start block (inclusive) |
| `toBlock`   | `number` | Yes      | End block (inclusive)   |

Maximum range: 2000 blocks per request.

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/events?fromBlock=24921292&toBlock=24922675" />

**Response**

```json
{
  "events": [
    {
      "block": { "blockNumber": 24921350, "blockTimestamp": 1776691000 },
      "eventType": "swap",
      "txnId": "0x7576a097a1680a8ec8a595212572b49e0d9cc8d64cfdcd891f5bc2bce2aa2178",
      "txnIndex": 4,
      "eventIndex": 0,
      "maker": "0xB2A9f3886134e5F6A19a1A87bD62343FE2685c64",
      "pairId": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
      "asset1In": "0.5",
      "asset0Out": "966424.684",
      "priceNative": "0.00000063",
      "reserves": {
        "asset0": "29569970.09",
        "asset1": "0.61"
      }
    }
  ]
}
```

Each event is a swap. `asset0` is always the btoken; `asset1` is always the reserve token.

| Field             | Type     | Description                                    |
| :---------------- | :------- | :--------------------------------------------- |
| `eventType`       | `"swap"` | Always `"swap"`                                |
| `txnId`           | `string` | Transaction hash                               |
| `txnIndex`        | `number` | Transaction order within block                 |
| `eventIndex`      | `number` | Event order within transaction                 |
| `maker`           | `string` | Wallet that submitted the transaction          |
| `pairId`          | `string` | btoken address                                 |
| `asset1In`        | `string` | Reserve amount in (buy)                        |
| `asset0Out`       | `string` | btoken amount out (buy)                        |
| `asset0In`        | `string` | btoken amount in (sell)                        |
| `asset1Out`       | `string` | Reserve amount out (sell)                      |
| `priceNative`     | `string` | Price of asset0 quoted in asset1 (decimalized) |
| `reserves.asset0` | `string` | Post-swap btoken pool balance                  |
| `reserves.asset1` | `string` | Post-swap reserve pool balance                 |

All amounts are decimalized (`amount / 10 ** decimals`).

**Errors**

| Status | Body                                                 | Cause                               |
| :----- | :--------------------------------------------------- | :---------------------------------- |
| `400`  | `{ error: "Block range exceeds max range of 2000" }` | Range greater than 2000 blocks      |
| `400`  | `{ error: [{ message: "..." }] }`                    | Missing or invalid query parameters |

***

### GET /v1/coingecko/:chain/tickers

Returns all active Baseline pools on a chain with current price, volume, and liquidity data. Responses are cached for 30 seconds.

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/tickers" />

**Response**

```json
[
  {
    "ticker_id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "base_currency": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "target_currency": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "pool_id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
    "last_price": "0.00000063",
    "base_volume": "966424.68430129",
    "target_volume": "0.61341692",
    "liquidity_in_usd": "31086",
    "high": "0.00000064",
    "low": "0.00000060"
  }
]
```

`ticker_id` is formatted as `BTOKEN_RESERVE`. `base_currency` is the btoken; `target_currency` is the reserve asset.

***

### GET /v1/coingecko/:chain/orderbook

Returns an empty orderbook stub. Baseline uses an AMM with no traditional order book.

**Query parameters**

| Parameter   | Type     | Required | Description                        |
| :---------- | :------- | :------- | :--------------------------------- |
| `ticker_id` | `string` | Yes      | Pair ID in `BTOKEN_RESERVE` format |

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/orderbook?ticker_id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" />

**Response**

```json
{
  "ticker_id": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "timestamp": "1776770625054",
  "bids": [],
  "asks": []
}
```

***

### GET /v1/coingecko/:chain/historical\_trades

Returns historical trades for a pair within an optional time window on a chain.

**Query parameters**

| Parameter    | Type                | Required | Description                        |
| :----------- | :------------------ | :------- | :--------------------------------- |
| `ticker_id`  | `string`            | Yes      | Pair ID in `BTOKEN_RESERVE` format |
| `type`       | `"buy"` \| `"sell"` | No       | Filter by trade direction          |
| `limit`      | `number`            | No       | Max trades to return               |
| `start_time` | `number`            | No       | Unix timestamp start (inclusive)   |
| `end_time`   | `number`            | No       | Unix timestamp end (inclusive)     |

<ApiExample url="https://api.baseline.markets/v1/coingecko/ethereum/historical_trades?ticker_id=0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&limit=1" />

**Response**

```json
{
  "buy": [
    {
      "trade_id": "0x7a68e9216c6e238e6388dd67e737e3de92c5c93b:1",
      "price": "0.00000063",
      "base_volume": "966424.68",
      "target_volume": "0.61",
      "trade_timestamp": "1776706931000",
      "type": "buy"
    }
  ],
  "sell": []
}
```

***

## Points and leaderboard

### GET /v1/points/:walletAddress

Returns points summary for a wallet — cumulative all-time points and per-week breakdown.

**Path parameters**

| Parameter       | Type     | Description                    |
| :-------------- | :------- | :----------------------------- |
| `walletAddress` | `string` | Checksummed EVM wallet address |

<ApiExample url="https://api.baseline.markets/v1/points/0x89C6AD1CC1c22c8705670a8600541fEf162e77Cf" />

**Response**

```json
{
  "wallet": "0x89C6AD1CC1c22c8705670a8600541fEf162e77Cf",
  "referralPoints": "0",
  "cumulative": {
    "totalPoints": "100000",
    "totalVolumeUsd": "209",
    "rank": 1
  },
  "currentWeek": {
    "weekStart": 1776056400,
    "points": "100000",
    "volumeUsd": "209",
    "rank": 1
  },
  "weeklyHistory": [
    {
      "weekStart": 1776056400,
      "weekEnd": 1776661200,
      "points": "100000",
      "volumeUsd": "209"
    }
  ]
}
```

***

### GET /v1/leaderboard

Returns the points leaderboard with pagination.

**Query parameters**

| Parameter    | Type              | Default | Description                                                  |
| :----------- | :---------------- | :------ | :----------------------------------------------------------- |
| `period`     | `"all"` \| `"1w"` | `"all"` | All-time or weekly leaderboard                               |
| `limit`      | `number`          | `10`    | Results per page (max 500)                                   |
| `offset`     | `number`          | `0`     | Pagination offset                                            |
| `search`     | `string`          | —       | Filter by wallet address substring                           |
| `week_start` | `number`          | —       | Unix timestamp of a specific week start (overrides `period`) |

<ApiExample url="https://api.baseline.markets/v1/leaderboard?period=1w&limit=1" />

**Response**

```json
{
  "entries": [
    {
      "rank": 1,
      "wallet": "0xe8d6d566c2B9eBBCcb4072ab5FffbD1dfe016721",
      "points": "63935",
      "volumeUsd": "922",
      "weightedVolume": "922",
      "referralWeightedVolume": "0",
      "totalWeightedVolume": "922",
      "breakdown": [
        {
          "btokenAddress": "0x7a68e9216C6e238e6388Dd67E737E3De92C5C93B",
          "btokenSymbol": "BLT",
          "reserveSymbol": "WETH",
          "volumeUsd": 922.08,
          "multiplier": 1,
          "weightedVolume": 922.08
        }
      ],
      "referralCount": 0
    }
  ],
  "totalEntries": 4,
  "totalWeightedVolume": 1442,
  "totalPoints": 100000,
  "totalVolume": 1442
}
```

***

### GET /v1/leaderboard/weeks

Returns a list of completed weeks with their points pool sizes, ordered most-recent first.

<ApiExample url="https://api.baseline.markets/v1/leaderboard/weeks" />

**Response**

```json
{
  "weeks": [
    { "week_start": 1776056400, "points_pool": 100000 }
  ]
}
```