# Trades & candles

> Trade tape with real-trader attribution, OHLCV candles from 1 second to 1 day, and a unified activity feed for any Robinhood Chain token.

Source: https://crius.sh/docs/reference/trades/

The trade tape, candles and the full activity feed of a token.

**Who actually traded.** On-chain, `tx.from` and the swap's sender are often infrastructure: routers, aggregators, Relay solvers, ERC-4337 bundlers, launchpad helpers, bot contracts. Every trade is attributed to the address whose balance actually changed (the **trader**), and the infrastructure that sent it is reported separately as `executor` and `signer`. One transaction can contain several trades.

| Endpoint | Method | Plan | Credits |
|---|---|---|---|
| [Trade tape](#trade-tape) | `GET /v1/{chain}/token/{address}/trades` | Anonymous | 2 |
| [OHLCV candles](#ohlcv-candles) | `GET /v1/{chain}/token/{address}/candles` | Anonymous | 2 |
| [Activity feed](#activity-feed) | `GET /v1/{chain}/token/{address}/transactions` | Free | 2 |

## Trade tape

**GET** `/v1/{chain}/token/{address}/trades`

**Plan:** Anonymous and above (no key needed) · **Cost:** 2 credits per call

Newest first. Each trade carries side, amounts in human units, USD and ETH value, the price, pool and DEX, the attributed trader, gas and token tax, and its `finality` (`latest` → `safe` → `finalized`). Filter by `side`, `trader`, `min_usd` and a time range; paginate with `cursor`.

> Real trader attribution, USD at trade time, realized tax, gas (L2 + L1).

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `limit` | query | integer | `50` | Maximum number of items to return. Up to 500. |
| `cursor` | query | string |  | Pagination cursor from the previous response's `meta.next_cursor`. |
| `side` | query | string |  | `buy` or `sell`. |
| `trader` | query | string |  | Only trades by this trader address. |
| `min_usd` | query | number |  | Only items worth at least this many USD. |
| `from_ts` | query | integer |  | Start of the time range, unix milliseconds (inclusive). |
| `to_ts` | query | integer |  | End of the time range, unix milliseconds (inclusive). |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/trades?limit=3" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/trades?limit=3", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/trades?limit=3",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

[Try it in the playground →](https://crius.sh/docs/playground/?op=GET%20%2Fv1%2F%7Bchain%7D%2Ftoken%2F%7Baddress%7D%2Ftrades)

### Example response

Real response captured from the API (arrays trimmed to three items).

```json
{
  "data": [
    {
      "amount_base": 0.0007766108202848,
      "amount_quote": 1.851107,
      "block": 95504366,
      "dex": "uniswap_v3",
      "eth_usd_at_trade": 2383.18,
      "executor": null,
      "fees": {
        "gas": {
          "gas_price_gwei": 0.02021,
          "gas_used": 325451,
          "gas_used_l1": 0,
          "l1_eth": 0,
          "l2_eth": 0.00000657736,
          "total_eth": 0.00000657736,
          "usd": 0.0156671
        },
        "token_tax": {
          "pct": null
        }
      },
      "finality": "latest",
      "id": "95504366-2-6",
      "market_cap_usd_at_trade": 98354693,
      "pool": "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
      "price_eth": 1.00016,
      "price_usd": 2383.57,
      "quote": "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
      "quote_symbol": "USDG",
      "signer": "0xafa54e6945803ec0025bb5adf7dea1e50c32bb41",
      "trader": "0xafa54e6945803ec0025bb5adf7dea1e50c32bb41",
      "ts": 1792712992000,
      "tx": "0x413b63acc6148916f503f8ec69cf084dd245a3306c35f813256b4236f0f46fd8",
      "tx_index": 2,
      "type": "buy",
      "value_eth": 0.000776738,
      "value_usd": 1.85111,
      "via": []
    },
    {
      "amount_base": 0.004912218011682397,
      "amount_quote": 11.706273,
      "block": 95504363,
      "dex": "uniswap_v3",
      "eth_usd_at_trade": 2383.18,
      "executor": null,
      "fees": {
        "gas": {
          "gas_price_gwei": 0.02004,
          "gas_used": 545154,
          "gas_used_l1": 0,
          "l1_eth": 0,
          "l2_eth": 0.0000109249,
          "total_eth": 0.0000109249,
          "usd": 0.0260228
        },
        "token_tax": {
          "pct": null
        }
      },
      "finality": "latest",
      "id": "95504363-24-9",
      "market_cap_usd_at_trade": 98334976,
      "pool": "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
      "price_eth": 0.999964,
      "price_usd": 2383.09,
      "quote": "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
      "quote_symbol": "USDG",
      "signer": "0xa635592405b43dd06c8e801e61310ba64287856a",
      "trader": "0xa635592405b43dd06c8e801e61310ba64287856a",
      "ts": 1792712992000,
      "tx": "0x7125a0df6c354f157facaa6b0133caca6a15b37eccd28050a6fd431efb06d290",
      "tx_index": 24,
      "type": "sell",
      "value_eth": 0.00491204,
      "value_usd": 11.7063,
      "via": [
        "okx_dex_router"
      ]
    },
    {
      "amount_base": 0.015072639336010453,
      "amount_quote": 35.926685,
      "block": 95504354,
      "dex": "uniswap_v3",
      "eth_usd_at_trade": 2383.18,
      "executor": null,
      "fees": {
        "gas": {
          "gas_price_gwei": 0.02007,
          "gas_used": 425441,
          "gas_used_l1": 0,
          "l1_eth": 0,
          "l2_eth": 0.0000085386,
          "total_eth": 0.0000085386,
          "usd": 0.0203387
        },
        "token_tax": {
          "pct": null
        }
      },
      "finality": "latest",
      "id": "95504354-24-11",
      "market_cap_usd_at_trade": 98354637,
      "pool": "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca",
      "price_eth": 1.00016,
      "price_usd": 2383.57,
      "quote": "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
      "quote_symbol": "USDG",
      "signer": "0x97c18ecd26897974a003fce7dbb18306da4fcb54",
      "trader": "0x97c18ecd26897974a003fce7dbb18306da4fcb54",
      "ts": 1792712991000,
      "tx": "0xc6a0696a05853a04dee75c0abd0ff42cacbf440949e67245fd0f302b2dc2eef9",
      "tx_index": 24,
      "type": "buy",
      "value_eth": 0.0150751,
      "value_usd": 35.9267,
      "via": []
    }
  ],
  "meta": {
    "block": 95504399,
    "block_age_ms": 1155,
    "block_ts": 1792712995000,
    "chain": "robinhood",
    "finalized_block": 95493649,
    "lag_ms": 7,
    "next_cursor": "95504354-11",
    "safe_block": 95497061
  }
}
```

## OHLCV candles

**GET** `/v1/{chain}/token/{address}/candles`

**Plan:** Anonymous and above (no key needed) · **Cost:** 2 credits per call

Candles in **columnar** form (one array per field, aligned by index), which is compact and maps straight onto charting libraries. Intervals: `1s`, `30s`, `1m`, `5m`, `15m`, `1h`, `4h`, `6h`, `1d`. Up to 1,500 candles per call; buckets without trades are omitted.

By default (USD) candles merge the token's real markets: every pool with at least $1k or 2% of its liquidity, plus its launch curve for launchpad tokens. Thin side pools stay out, so a $1 trade there can't draw a wick. `pool=main` charts the main market only (the default with `currency=quote`, prices in the pool's quote token), `pool=<key>` one pool, `pool=all` every pool. Each candle opens at the previous close (`continuous=false` for first-trade opens), and `fill=true` adds flat candles for buckets without trades so the time axis is evenly spaced. Dust trades (under 10,000 raw units on either side) never set a price.

See the [chart example](https://crius.sh/docs/examples/chart/) for a complete TradingView Lightweight Charts integration.

> Default (usd): the token's real markets merged (pools with >= $1k or >= 2% of its liquidity) plus its launch curve; ?pool=main its main market only; ?pool=all every pool. Candles open at the previous close.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `interval` | query | string | `1m` | Bucket size. One of `1s`, `30s`, `1m`, `5m`, `15m`, `1h`, `4h`, `6h`, `1d`. |
| `limit` | query | integer | `500` | Maximum number of items to return. |
| `from_ts` | query | integer |  | Start of the time range, unix milliseconds (inclusive). |
| `to_ts` | query | integer |  | End of the time range, unix milliseconds (inclusive). |
| `currency` | query | string | `usd` | Price unit. One of `usd`, `quote`. |
| `pool` | query | string |  | Pool address (Uniswap v2/v3) or 32-byte pool id (Uniswap v4). Markets (default for usd) \| main (default for quote) \| all \| a pool id. |
| `continuous` | query | boolean | `true` | `true`: the holder must stay above the threshold for the whole window. Open = previous close. |
| `fill` | query | boolean | `false` | Flat candles for buckets without trades. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/candles?interval=1h&limit=3" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/candles?interval=1h&limit=3", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x0bd7d308f8e1639fab988df18a8011f41eacad73/candles?interval=1h&limit=3",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

[Try it in the playground →](https://crius.sh/docs/playground/?op=GET%20%2Fv1%2F%7Bchain%7D%2Ftoken%2F%7Baddress%7D%2Fcandles)

### Key response fields

- `t`: bucket start (unix ms) · `o` `h` `l` `c`: open, high, low, close
- `v`: USD volume · `bv`: buy volume (sell volume = `v − bv`) · `n`: number of trades · `mc`: market cap at close

### Example response

Real response captured from the API (arrays trimmed to three items).

```json
{
  "data": {
    "bv": [
      2691794,
      1743314,
      1039396
    ],
    "c": [
      2390.77,
      2382.33,
      2383.09
    ],
    "currency": "usd",
    "h": [
      2473.01,
      2395.33,
      2457.6
    ],
    "interval": "1h",
    "l": [
      1416.96,
      2176.09,
      2377.71
    ],
    "mc": [
      98652729,
      98304422,
      98335812
    ],
    "n": [
      5776,
      4388,
      2734
    ],
    "o": [
      2379.84,
      2390.81,
      2381.85
    ],
    "t": [
      1792702800000,
      1792706400000,
      1792710000000
    ],
    "v": [
      5065109,
      3747088,
      2040556
    ]
  },
  "meta": {
    "block": 95504408,
    "block_age_ms": 994,
    "block_ts": 1792712996000,
    "chain": "robinhood",
    "finalized_block": 95493649,
    "from_ts": 1792702800000,
    "lag_ms": 2,
    "note": "buckets without trades are omitted; default = the token's main market (its pricing pool) plus its launch curve for launchpad tokens; ?pool=markets merges its real markets, ?pool=<key> one pool, ?pool=all every pool",
    "pools": [
      "0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca"
    ],
    "safe_block": 95497061,
    "to_ts": 1792712996000
  }
}
```

## Activity feed

**GET** `/v1/{chain}/token/{address}/transactions`

**Plan:** Free and above · **Cost:** 2 credits per call

One chronological feed of everything that happened to the token: buys and sells, liquidity adds and removes, plain transfers, mints and burns, LP lock events, fee claims, owner actions on the contract (`renounceOwnership`, `openTrading`, setters, upgrades) and launchpad lifecycle events. Filter with `type` (comma list), `wallet`, `min_usd`, `from`/`to` and `finality`.

> Trades, liquidity adds/removes, transfers, mints/burns, owner actions (decoded), locks, fee claims, launch / graduation.

### Parameters

| Name | In | Type | Default | Description |
|---|---|---|---|---|
| `chain` | path, required | string |  | Chain slug (`robinhood`) or chain id (`4663`). |
| `address` | path, required | string |  | Contract or wallet address, any case (`0x…`, 20 bytes). |
| `type` | query | string |  | Filter by item type. Comma list of `buy`, `sell`, `add_liquidity`, `remove_liquidity`, `transfer`, `mint`, `burn`, `owner_action`, `lock`, `fee_claim`, `launch`, `graduation`. |
| `wallet` | query | string |  | Only events involving this wallet. |
| `min_usd` | query | number |  | Only items worth at least this many USD. |
| `from` | query | string |  | Start of the window (`block:`, `ts:`, `mcap:` or a label). One of `block:N`, `ts:MS`, `mcap:USD`, `launch`, `trading_open`, `graduation`, `ath`. |
| `to` | query | string |  | End of the window (same forms as `from`). |
| `finality` | query | string |  | Only rows at or below this finality level. One of `latest`, `safe`, `finalized`. |
| `limit` | query | integer | `50` | Maximum number of items to return. |
| `cursor` | query | string |  | Pagination cursor from the previous response's `meta.next_cursor`. |

### Request

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/transactions?limit=20" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/transactions?limit=20", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/transactions?limit=20",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```