Retrieve trade history for the authenticated user within a date range.
start_time
datetime.datetime
required
Start datetime for the trade history range
end_time
datetime.datetime
required
End datetime for the trade history range
Optional market ID to filter trades. If None, returns all trades.
Dictionary containing orders data if found, None otherwise
Orders include both open and closed orders with full details:
- owner, orderId, timestamp, marketId, market
- type, side, thresholdPrice, size, leverage
- status, filledSize, reduceOnly, canceled
- ValueError — If API_SERVER_URL or ACCOUNT environment variable is not set
Example
>>> import os
>>> import datetime
>>> os.environ["API_SERVER_URL"] = "http://localhost:8080"
>>> os.environ["ACCOUNT"] = "0x1234..."
>>> start = datetime.datetime(2026, 1, 1)
>>> end = datetime.datetime(2026, 1, 15)
>>> # Get all trades
>>> history = await getTradeHistory(start, end)
>>> print(len(history["orders"]))
25
>>> # Get trades for specific market
>>> history = await getTradeHistory(start, end, market_id=10)
>>> print(len(history["orders"]))
5
async def getTradeHistory(start_time: datetime.datetime, end_time: datetime.datetime, market_id: Optional[Union[str, int]]=None) -> Optional[Dict[str, Any]]:
base_url = os.getenv('API_SERVER_URL')
if not base_url:
raise ValueError('API_SERVER_URL environment variable not set')
address = os.getenv('ACCOUNT')
if not address:
raise ValueError('ACCOUNT environment variable not set')
async with httpx.AsyncClient() as session:
client = PerpetualsClient(base_url=base_url, session=session)
try:
start_time_pb = Timestamp()
end_time_pb = Timestamp()
start_time_pb.FromDatetime(start_time)
end_time_pb.FromDatetime(end_time)
orders = await client.get_trade_history(address=address, startTime=start_time_pb, endTime=end_time_pb)
if orders is not None:
orders_list = [MessageToDict(order, always_print_fields_with_no_presence=True) for order in orders]
if market_id is not None:
orders_list = [order for order in orders_list if order.get('marketId') == market_id]
orders_list.sort(key=lambda o: o.get('timestamp', ''), reverse=True)
return {'orders': orders_list}
return None
except Exception as e:
print(f'Error getting trade history: {e}')
print('\nTroubleshooting:')
print(' - Is the server running?')
print(' - Is ACCOUNT environment variable set correctly?')
print(' - Check the date range is valid')
print(' - Check network connectivity')
return None
