Get Balance Updates

Retrieve historical deposit, withdrawal, and transfer transactions for a subaccount. This endpoint returns balance changes from on-chain deposits, withdrawals, and internal transfers, excluding funding payments.

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "getBalanceUpdates",
    "subAccountId": "1867542890123456789",
    "actionFilter": "DEPOSIT",
    "limit": 50,
    "offset": 0,
    "startTime": 1704067200000,
    "endTime": 1704153600000
  },
  "expiresAfter": 1704153600,
  "signature": {
    "v": 28,
    "r": "0x19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef",
    "s": "0xabcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600abcdef19480589384695193600"
  }
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"getBalanceUpdates"`
`params.subAccountId`	string	Yes	SubAccount ID to retrieve balance updates for
`params.actionFilter`	string	No	Filter by action type: `"DEPOSIT"`, `"WITHDRAWAL"`, `"TRANSFER"`, or comma-separated (e.g. `"DEPOSIT,WITHDRAWAL"`). Defaults to all types
`params.limit`	integer	No	Maximum number of results to return (default: 50, max: 1000)
`params.offset`	integer	No	Pagination offset (default: 0, max: 10000)
`params.startTime`	integer	No	Start of time range as Unix timestamp in milliseconds. Defaults to 7 days before `endTime` (or 7 days ago if neither is set)
`params.endTime`	integer	No	End of time range as Unix timestamp in milliseconds. Defaults to 7 days after `startTime` (or now if neither is set). Maximum range is 365 days

Parameter	Type	Required	Description
`nonce`	uint64	Yes*	Positive integer nonce (must be incrementing and unique per request)
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	uint64	No	Unix milliseconds expiration timestamp (5x rate limit on stale cancels)

:::info Common Parameters These are top-level request parameters. The subAccountId parameter is specified within the params object (see each endpoint's parameter table). :::

:::info SubAccountAction Endpoints Endpoints using SubAccountAction signing (getPositions, getOpenOrders, getOrderHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates, getWithdrawableAmounts, getFeeRate, getSnaxpotEpochTickets) do not require the nonce parameter. Only signature and optional expiresAfter are needed. :::

Response

Response Structure

Field	Type	Description
`status`	string	Always `"ok"` for successful requests or `"error"` for failures
`response`	object	Response object containing balance updates (omitted when `status` is `"error"`)
`error`	object	Error details (only present when `status` is `"error"`)
`request_id`	string	Request tracking identifier

Success Response

{
  "status": "ok",
  "response": {
    "balanceUpdates": [
      {
        "id": "12345",
        "subAccountId": "1867542890123456789",
        "action": "DEPOSIT",
        "status": "success",
        "amount": "1000.00",
        "fee": "0.00",
        "grossAmount": "1000.00",
        "collateral": "USDT",
        "usdtNotional": "1000.00",
        "timestamp": 1704067200000
      },
      {
        "id": "12346",
        "subAccountId": "1867542890123456789",
        "action": "WITHDRAWAL",
        "status": "success",
        "amount": "-500.00",
        "fee": "5.00",
        "grossAmount": "-495.00",
        "collateral": "USDT",
        "usdtNotional": "500.00",
        "timestamp": 1704153600000,
        "destinationAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  },
  "request_id": "5ccf215d37e3ae6d"
}

Empty Result

{
  "status": "ok",
  "response": {
    "balanceUpdates": []
  },
  "request_id": "5ccf215d37e3ae6f"
}

Balance Update Object

Field	Type	Description
`id`	string	Unique transaction ID (string for JS BigInt compatibility)
`subAccountId`	string	Subaccount ID associated with the transaction (string for JS BigInt compatibility)
`action`	string	Action type: `"DEPOSIT"`, `"WITHDRAWAL"`, or `"TRANSFER"`
`status`	string	Transaction status: `"pending"`, `"success"`, or `"failed"`
`amount`	string	Net amount changed (positive for deposits, negative for withdrawals)
`fee`	string	Fee charged for the transaction
`grossAmount`	string	Total amount including fee (`amount + fee`)
`collateral`	string	Collateral symbol (e.g., `"USDT"`, `"WETH"`)
`usdtNotional`	string	Spot USDT value of the transaction at the time it occurred. Always present
`timestamp`	integer	Unix timestamp in milliseconds when the transaction was created
`destinationAddress`	string	Destination address for withdrawals (optional, only for withdrawals)
`txHash`	string	On-chain transaction hash (optional)
`fromSubAccountId`	string	Source subaccount ID for internal transfers (optional, string for JS BigInt compatibility)
`toSubAccountId`	string	Target subaccount ID for internal transfers (optional, string for JS BigInt compatibility)

Error Response

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit cannot exceed 1000"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Usage Examples

Get All Balance Updates

{
  "params": {
    "action": "getBalanceUpdates",
    "subAccountId": "1867542890123456789"
  },
  "expiresAfter": 1704153600,
  "signature": { "v": 28, "r": "0x...", "s": "0x..." }
}

Get Deposits Only

{
  "params": {
    "action": "getBalanceUpdates",
    "subAccountId": "1867542890123456789",
    "actionFilter": "DEPOSIT"
  },
  "expiresAfter": 1704153600,
  "signature": { "v": 28, "r": "0x...", "s": "0x..." }
}

Get Withdrawals Only

{
  "params": {
    "action": "getBalanceUpdates",
    "subAccountId": "1867542890123456789",
    "actionFilter": "WITHDRAWAL"
  },
  "expiresAfter": 1704153600,
  "signature": { "v": 28, "r": "0x...", "s": "0x..." }
}

Paginated Request

{
  "params": {
    "action": "getBalanceUpdates",
    "subAccountId": "1867542890123456789",
    "limit": 100,
    "offset": 100
  },
  "expiresAfter": 1704153600,
  "signature": { "v": 28, "r": "0x...", "s": "0x..." }
}

EIP-712 Signature

const domain = {
  name: "Synthetix",
  version: "1",
  chainId: 1,
  verifyingContract: "0x0000000000000000000000000000000000000000",
};
 
const types = {
  SubAccountAction: [
    { name: "subAccountId", type: "uint256" },
    { name: "action", type: "string" },
    { name: "expiresAfter", type: "uint256" },
  ],
};
 
const message = {
  subAccountId: "1867542890123456789",
  action: "getBalanceUpdates",
  expiresAfter: 0,
};
 
const signature = await signer._signTypedData(domain, types, message);

Implementation Notes

Returns deposit, withdrawal, and internal transfer transactions (excludes funding payments)
Results are ordered by timestamp (most recent first)
Default limit is 50 results per request, maximum is 1000
Pagination offset maximum is 10,000
Use pagination with limit and offset for large result sets
When startTime and endTime are both omitted, the default time window is the last 7 days
When only one time bound is supplied, the other is automatically extended by 7 days (end time is capped at now)
Maximum allowed time range is 365 days; requests spanning a longer period are rejected
For funding payment history, use Get Funding Payments
Authentication requires signature by account owner or authorized delegate

Signing

All trading methods are signed using EIP-712. Each successful trading request will contain:

A piece of structured data that includes the sender address
A signature of the hash of that structured data, signed by the sender

For detailed information on EIP-712 signing, see EIP-712 Signing.

Nonce Management

The nonce system prevents replay attacks and ensures order uniqueness:

Use any positive integer as nonce
Each nonce must be greater than the previous one (incrementing)
Date.now() is a convenient option, not a requirement
If nonce conflicts occur, increment by 1 and retry

:::note SubAccountAction Exception SubAccountAction endpoints (getPositions, getOpenOrders, getOrderHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates, getWithdrawableAmounts, getFeeRate, getSnaxpotEpochTickets) do not require a nonce. Only the signature and optional expiresAfter parameters are needed. :::

Error Handling

Common error scenarios:

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

Error Code	Message	Description
`VALIDATION_ERROR`	`subAccountId is required`	No subaccount ID was provided
`VALIDATION_ERROR`	`limit cannot exceed 1000`	Limit parameter exceeds maximum
`VALIDATION_ERROR`	`limit must be non-negative`	Negative limit value provided
`VALIDATION_ERROR`	`offset must be non-negative`	Negative offset value provided
`VALIDATION_ERROR`	`offset cannot exceed 10000`	Offset exceeds maximum of 10000
`VALIDATION_ERROR`	`invalid action filter, available filters: DEPOSIT, WITHDRAWAL, TRANSFER`	Invalid action filter value
`INTERNAL_ERROR`	`Failed to retrieve balance updates`	Server error retrieving data

Related Endpoints

Get Subaccount - View current account balances and margin status
Get Funding Payments - Funding payment history (separate from deposits/withdrawals)