Hyperliquid

Market Trades

Returns the Hyperliquid trade feed filtered by coin, market type, and optional buyer and/or seller address. Market type is always applied. When buyer, seller, and symbol are all ALL, the query returns the most recent 12 hours of trades regardless of start_time / end_time.

POST/v2/semantic/retrieve/parameterized

Query Parameters

symbolstring

Coin ticker filter. ALL returns every coin.

Example:

"ETH"

market_typestring

Market type: perp, spot, or outcome. Always applied — there is no ALL bypass, so a value of ALL matches no rows. Required.

Example:

"perp"

buyerstring

Buyer address filter. Lower-cased before matching. ALL returns every buyer.

Example:

"ALL"

sellerstring

Seller address filter. Lower-cased before matching. ALL returns every seller.

Example:

"ALL"

start_timestring

Trades at or after this time, in seconds. The sentinel 1600000000 disables the lower bound.

Example:

"1600000000"

end_timestring

Trades at or before this time, in seconds. The sentinel 2200000000 disables the upper bound.

Example:

"2200000000"

Response Fields

Field	Type	Description
`tid`	Integer	Trade identifier
`symbol`	String	Coin ticker
`side`	String	Aggressor side: `B` (taker buy) or `A` (taker sell)
`price`	Number	Execution price
`size`	Number	Trade size in base units
`trade_time`	String (ISO 8601)	Execution time
`hash`	String	Transaction hash
`buyer`	String	Buyer address
`seller`	String	Seller address
`is_liquidation`	Boolean	Whether the trade was a liquidation
`market_type`	String	Market type (`perp` / `spot` / `outcome`)

Market Trades

curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 613,
  "params": {
    "symbol": "ETH",
    "market_type": "perp",
    "buyer": "ALL",
    "seller": "ALL",
    "start_time": "1600000000",
    "end_time": "2200000000"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'

200Example response

{
  "timestamp": "",
  "params": {
    "symbol": "ETH",
    "market_type": "perp",
    "buyer": "ALL",
    "seller": "ALL",
    "start_time": "1600000000",
    "end_time": "2200000000"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "tid": 365738602585856,
        "symbol": "ETH",
        "side": "A",
        "price": 2185.6,
        "size": 0.05,
        "trade_time": "2026-05-17T18:53:55.967000Z",
        "hash": "0x948051c3b082fb2395fa043b9fa8150204f700a94b8619f53848fd166f86d50e",
        "buyer": "0x31dea2516beee92135b96f464eeec3cf292a13f2",
        "seller": "0xaf8c393fd40c20accef9fa691d43400ebcfcc9ae",
        "is_liquidation": false,
        "market_type": "perp"
      },
      {
        "tid": 980367930467703,
        "symbol": "ETH",
        "side": "A",
        "price": 2185.6,
        "size": 0.01,
        "trade_time": "2026-05-17T18:53:55.967000Z",
        "hash": "0x948051c3b082fb2395fa043b9fa8150204f700a94b8619f53848fd166f86d50e",
        "buyer": "0x492322b1fca1ab301a103b716a243b20cb3001aa",
        "seller": "0xaf8c393fd40c20accef9fa691d43400ebcfcc9ae",
        "is_liquidation": false,
        "market_type": "perp"
      }
    ]
  }
}