Recent Trades

Query historical trade executions for a specific Deepbook pool. Returns completed trades including price, quantities, fees, and on-chain metadata. Use this endpoint to power recent trades feeds, volume calculations, and market analysis.

Endpoint

GET /deepbook/{poolName}/trades

Use Cases

• Recent Trades Feed — Display latest executed trades in trading interfaces
• Volume Metrics — Calculate trading volume over specific time periods
• Price History — Track executed prices for market analysis
• Trade Analytics — Analyze maker/taker ratios, fee distributions, and order flow
• Market Surveillance — Monitor trading activity and detect unusual patterns

Parameters

Path Parameters

Parameter	Type	Required	Description
poolName	string	Yes	The Deepbook pool name (e.g., "SUI_USDC")

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	100	Maximum number of trades to return (min 1, max 100)
from	number	No	-1 day	Start timestamp in seconds (UNIX timestamp). Defaults to 1 day ago.
to	number	No	now	End timestamp in seconds (UNIX timestamp). Defaults to current time.
api-key	string	Yes	—	Your Surflux API key for authentication

Response

Returns an array of trade objects, ordered from most recent to oldest.

Field	Type	Description
event_digest	string	Unique identifier for the event on-chain
digest	string	Transaction digest (hash)
sender	string	Address that initiated the transaction
checkpoint	number	Checkpoint number when the trade was executed
checkpoint_timestamp_ms	number	Timestamp in milliseconds
package	string	Deepbook package address
pool_id	string	Pool identifier where the trade occurred
maker_order_id	string	Maker's order ID
taker_order_id	string	Taker's order ID
maker_client_order_id	string	Client-assigned maker order ID
taker_client_order_id	string	Client-assigned taker order ID
price	number	Execution price (in smallest units)
taker_fee	number	Fee paid by taker
taker_fee_is_deep	boolean	Whether taker fee was paid in DEEP tokens
maker_fee	number	Fee paid by maker
maker_fee_is_deep	boolean	Whether maker fee was paid in DEEP tokens
taker_is_bid	boolean	True if taker was buying, false if selling
base_quantity	number	Quantity of base asset traded (in smallest units)
quote_quantity	number	Quantity of quote asset traded (in smallest units)
maker_balance_manager_id	string	Maker's balance manager address
taker_balance_manager_id	string	Taker's balance manager address
onchain_timestamp	number	On-chain timestamp in milliseconds

Example Response

[
  {
    "event_digest": "FgUfRsYpC6ynW3pRvtgCLaa4WniBZYdsSLP94jrZ3pj70",
    "digest": "FgUfRsYpC6ynW3pRvtgCLaa4WniBZYdsSLP94jrZ3pj7",
    "sender": "0xb117b12facd947cabb3d17d68a67b3d8d6865280edb0644cb4d25a9d86646966",
    "checkpoint": 193054501,
    "checkpoint_timestamp_ms": 1758629823918,
    "package": "0xf6cc231ead142d35c37494a4c36d9e78c97503c0be9f9a0652f6e1127304096a",
    "pool_id": "0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407",
    "maker_order_id": "170141183460531590950028478855175318595",
    "taker_order_id": "62359236787919212896114997",
    "maker_client_order_id": "5797765110082330991",
    "taker_client_order_id": "8",
    "price": 3380500,
    "taker_fee": 646286,
    "taker_fee_is_deep": true,
    "maker_fee": 0,
    "maker_fee_is_deep": false,
    "taker_is_bid": true,
    "base_quantity": 443700000000,
    "quote_quantity": 1499927850,
    "maker_balance_manager_id": "0x344c2734b1d211bd15212bfb7847c66a3b18803f3f5ab00f5ff6f87b6fe6d27d",
    "taker_balance_manager_id": "0x939adae6836dd87de7b7a2a48a5bd703dc1add7eb304d0c580217e000ccd2b10",
    "onchain_timestamp": 1758629823805
  }
]

Example Request

curl "https://api.surflux.dev/deepbook/SUI_USDC/trades?limit=100&api-key=YOUR_API_KEY"

const apiKey = 'YOUR_API_KEY';
const poolName = 'SUI_USDC';

// Get trades from the last hour
const now = Math.floor(Date.now() / 1000);
const oneHourAgo = now - 3600;

const url = `https://api.surflux.dev/deepbook/${poolName}/trades?from=${oneHourAgo}&to=${now}&limit=100&api-key=${apiKey}`;

const response = await fetch(url);
const trades = await response.json();

console.log(`Found ${trades.length} trades in the last hour`);

// Calculate total volume
const totalBaseVolume = trades.reduce((sum, trade) => sum + trade.base_quantity, 0);
const totalQuoteVolume = trades.reduce((sum, trade) => sum + trade.quote_quantity, 0);

console.log(`Total base volume: ${totalBaseVolume}`);
console.log(`Total quote volume: ${totalQuoteVolume}`);

Understanding Trade Data

Buy vs Sell Sides

The taker_is_bid field indicates the taker's side:

• true — Taker placed a buy order (bid), taking liquidity from sell side
• false — Taker placed a sell order (ask), taking liquidity from buy side

In most trading interfaces:

• Taker buy = Market buy = Green/bullish
• Taker sell = Market sell = Red/bearish

Price Calculation

Similar to order book depth, prices are in smallest units. Use pool metadata to convert:

// For SUI_USDC with 9 base decimals and 6 quote decimals
const rawPrice = 3380500;
const humanPrice = rawPrice / Math.pow(10, 6); // = 3.3805 USDC per SUI

Volume Calculation

Both base_quantity and quote_quantity are in smallest units:

// Base quantity (SUI with 9 decimals)
const baseVolume = trade.base_quantity / Math.pow(10, 9); // = 443.7 SUI

// Quote quantity (USDC with 6 decimals)
const quoteVolume = trade.quote_quantity / Math.pow(10, 6); // = 1499.93 USDC

Fee Structure

Deepbook supports fee payment in DEEP tokens or the quote asset:

• taker_fee_is_deep indicates if taker paid fees in DEEP tokens
• maker_fee_is_deep indicates if maker paid fees in DEEP tokens
• Makers typically pay lower fees (or zero fees) to incentivize liquidity provision

Time Range Queries

Use from and to parameters to query specific time ranges:

// Last 24 hours
const oneDayAgo = Math.floor(Date.now() / 1000) - 86400;
const url = `...?from=${oneDayAgo}&api-key=...`;

// Specific date range
const startDate = new Date('2025-01-01').getTime() / 1000;
const endDate = new Date('2025-01-31').getTime() / 1000;
const url = `...?from=${startDate}&to=${endDate}&api-key=...`;

Best Practices

• Paginate Large Queries — The limit is capped at 100 trades. If you need more, make multiple requests using the from and to parameters to split the time range.
• Cache Historical Data — Historical trades never change. Cache them locally to avoid repeated queries.
• Calculate VWAP — Use base_quantity and quote_quantity to calculate volume-weighted average price over any period.
• Monitor Recent Activity — Query the last few minutes of trades periodically to power "recent trades" feeds in UIs.
• Combine with Live Stream — Use this endpoint for historical backfill, then switch to Deepbook Flux Stream for real-time trade updates.