Hyperliquid

Wallet Trades

Returns Hyperliquid trades in which a given address is the buyer or seller. Each row is annotated with the queried address's role (trade_type), the counterparty on the other side, and the matched address. Filter by coin, market type, and time range.

POST/v2/semantic/retrieve/parameterized

Query Parameters

addressstring

Wallet address to match against both buyer and seller. Lower-cased before matching. Required.

Example:

"0x5a7581618829f377a16be2338eabdd03fece0eaf"

symbolstring

Coin ticker filter. ALL returns every coin.

Example:

"ALL"

market_typestring

Market type filter: perp, spot, or outcome. ALL returns every type.

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`)
`trade_type`	String	The queried address's role: `buyer` or `seller`
`counterparty`	String	The other party to the trade
`address`	String	The matched (queried) address, lower-cased

Wallet 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": 612,
  "params": {
    "address": "0x5a7581618829f377a16be2338eabdd03fece0eaf",
    "symbol": "ALL",
    "market_type": "ALL",
    "start_time": "1600000000",
    "end_time": "2200000000"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'

200Example response

{
  "timestamp": "",
  "params": {
    "address": "0x5a7581618829f377a16be2338eabdd03fece0eaf",
    "symbol": "ALL",
    "market_type": "ALL",
    "start_time": "1600000000",
    "end_time": "2200000000"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "tid": 563178213904701,
        "symbol": "BTC",
        "side": "B",
        "price": 78170,
        "size": 0.00217,
        "trade_time": "2026-05-17T18:53:55.967000Z",
        "hash": "0xed931b90908e03bdef0c043b9fa8150202f700762b81228f915bc6e34f81dda8",
        "buyer": "0x5a7581618829f377a16be2338eabdd03fece0eaf",
        "seller": "0xb668858ff53322d5511651a2cd92391eb5d60ee3",
        "is_liquidation": false,
        "market_type": "perp",
        "trade_type": "buyer",
        "counterparty": "0xb668858ff53322d5511651a2cd92391eb5d60ee3",
        "address": "0x5a7581618829f377a16be2338eabdd03fece0eaf"
      }
    ]
  }
}