Get Transfers (WebSocket)

Retrieve transfer history for a subaccount through the WebSocket connection. Returns collateral transfers between subaccounts with filtering and pagination support.

Endpoint

ws.send() wss://api.synthetix.io/v1/ws/trade

Request

Request Format

{
  "id": "transfers-1",
  "method": "post",
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "symbol": "USDT",
    "limit": 50,
    "offset": 0,
    "startTime": 1740220800000,
    "endTime": 1740307200000,
    "expiresAfter": 1704153600,
    "signature": {
      "v": 28,
      "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  }
}

Parameters

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Client-generated unique request identifier
`method`	string	Yes	Must be `"post"`
`params`	object	Yes	Contains all parameters for the request

Params Object

Parameter	Type	Required	Description
`action`	string	Yes	Must be `"getTransfers"`
`subAccountId`	string	Yes	Subaccount identifier
`symbol`	string	No	Filter by collateral symbol (e.g., `"USDT"`, `"WETH"`)
`limit`	integer	No	Maximum number of results to return (default: 50, max: 1000)
`offset`	integer	No	Pagination offset (default: 0)
`startTime`	number	No	Start timestamp in milliseconds. Cannot be more than 30 days in the past. When omitted, defaults to `now − 30 days`.
`endTime`	number	No	End timestamp in milliseconds. If `endTime` is older than 30 days and `startTime` is not provided, the request is rejected. Maximum range between `startTime` and `endTime`: 30 days.
`expiresAfter`	integer	No	Optional expiration timestamp in seconds
`signature`	object	Yes	EIP-712 signature using `SubAccountAction` type

Important Notes:

This endpoint uses SubAccountAction EIP-712 type (no nonce required)
30-day lookback cap: startTime cannot be more than 30 days in the past. When omitted, defaults to now − 30 days. If endTime is older than 30 days without an explicit startTime, the request is rejected.
Maximum time range is 30 days when using startTime and endTime
For deposit and withdrawal history, use Get Balance Updates

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: "getTransfers",
  expiresAfter: 0,
};
 
const signature = await signer._signTypedData(domain, types, message);

Response Format

Success Response

{
  "id": "transfers-1",
  "status": 200,
  "result": {
    "transfers": [
      {
        "transferId": "12345",
        "from": "2011391943438766080",
        "to": "3022502054549877191",
        "symbol": "USDT",
        "amount": "100",
        "transferType": "COLLATERAL_TRANSFER",
        "status": "success",
        "timestamp": 1740307200000
      },
      {
        "transferId": "12346",
        "from": "2011391943438766080",
        "to": "3022502054549877191",
        "symbol": "WETH",
        "amount": "0.5",
        "transferType": "COLLATERAL_TRANSFER",
        "status": "success",
        "timestamp": 1740220800000
      }
    ],
    "total": 2
  }
}

Empty Result

{
  "id": "transfers-1",
  "status": 200,
  "result": {
    "transfers": [],
    "total": 0
  }
}

Error Response

{
  "id": "transfers-1",
  "status": 400,
  "result": null,
  "error": {
    "code": 400,
    "message": "subAccountId is required"
  }
}

Response Fields

Transfer Object

Field	Type	Description
`transferId`	string	Unique transfer identifier (string for JS BigInt compatibility)
`from`	string	Source subaccount ID
`to`	string	Destination subaccount ID
`symbol`	string	Collateral symbol (e.g., `"USDT"`, `"WETH"`)
`amount`	string	Transfer amount as a decimal string
`transferType`	string	Transfer type (e.g., `"COLLATERAL_TRANSFER"`)
`status`	string	Transfer status (e.g., `"success"`, `"pending"`, `"failed"`)
`errorMessage`	string	Error details when the transfer failed (omitted when empty)
`timestamp`	number	Unix timestamp in milliseconds when the transfer occurred

Code Examples

Get All Transfers

{
  "id": "all-transfers",
  "method": "post",
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Filter by Symbol

{
  "id": "usdt-transfers",
  "method": "post",
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "symbol": "USDT",
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Filter by Time Range

{
  "id": "time-range",
  "method": "post",
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "startTime": 1740220800000,
    "endTime": 1740307200000,
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Paginated Request

{
  "id": "paginated",
  "method": "post",
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "limit": 100,
    "offset": 100,
    "expiresAfter": 0,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Implementation Notes

Results are ordered by timestamp (most recent first)
Default limit is 50 results per request, maximum is 1000
Maximum time range is 30 days when using startTime and endTime
Use pagination with limit and offset for large result sets
Authentication requires signature by account owner or authorized delegate
The API enforces a 30-day historical data retention limit. Providing a startTime older than 30 days returns a validation error.
When startTime is omitted, the query window is automatically anchored to 30 days before the request time. Integrators who previously omitted startTime to retrieve all history will now receive only the most recent 30 days. To access a specific earlier window, provide an explicit startTime within the 30-day retention period.

Common Errors

Error Code	Message	Description
400	subAccountId is required	No subaccount ID was provided
400	limit cannot exceed 1000	Limit parameter exceeds maximum
400	limit must be non-negative	Negative limit value provided
400	offset must be non-negative	Negative offset value provided
400	invalid request parameters	Invalid time range (exceeds 30 days)
400	startTime cannot be more than 30 days in the past	`startTime` is older than the 30-day historical data retention limit
400	endTime is older than the 30-day historical data cap	`endTime` is older than 30 days and `startTime` was not provided
500	failed to get transfers	Server error retrieving transfer data

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

Next Steps

Get Balance Updates - Deposit and withdrawal history
Get Subaccount - View current account balances
REST Alternative - REST API comparison