Get Transfers

Retrieve transfer history for a subaccount, including collateral transfers between subaccounts. Supports filtering by collateral symbol and time range, with pagination.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "symbol": "USDT",
    "limit": 50,
    "offset": 0,
    "startTime": 1740220800000,
    "endTime": 1740307200000
  },
  "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 `"getTransfers"`
`params.subAccountId`	string	Yes	SubAccount ID to retrieve transfers for
`params.symbol`	string	No	Filter by collateral symbol (e.g., `"USDT"`, `"WETH"`)
`params.limit`	integer	No	Maximum number of results to return (default: 50, max: 1000)
`params.offset`	integer	No	Pagination offset (default: 0)
`params.startTime`	number	No	Start timestamp in milliseconds. Must be within the last 30 days; values older than 30 days are rejected. When omitted, the query window begins 30 days before the request time.
`params.endTime`	number	No	End timestamp in milliseconds. Maximum range between `startTime` and `endTime`: 30 days. When `startTime` is omitted, `endTime` must also fall within the last 30 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, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) 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 transfers (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": {
    "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
  },
  "request_id": "5ccf215d37e3ae6d"
}

Empty Result

{
  "status": "ok",
  "response": {
    "transfers": [],
    "total": 0
  },
  "request_id": "5ccf215d37e3ae6f"
}

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

Error Response

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "subAccountId is required"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Usage Examples

Get All Transfers

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

Filter by Symbol

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

Filter by Time Range

{
  "params": {
    "action": "getTransfers",
    "subAccountId": "1867542890123456789",
    "startTime": 1740220800000,
    "endTime": 1740307200000
  },
  "expiresAfter": 1704153600,
  "signature": { "v": 28, "r": "0x...", "s": "0x..." }
}

Paginated Request

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

Implementation Notes

Returns transfer history including collateral transfers between subaccounts
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 using SubAccountAction EIP-712 type (no nonce required)
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.

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, getOrdersHistory, getTrades, getFundingPayments, getSubAccount, getSubAccounts, getDelegatedSigners, getBalanceUpdates) 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`	`invalid request parameters`	Invalid time range (exceeds 30 days)
`VALIDATION_ERROR`	`startTime cannot be more than 30 days in the past`	`startTime` is older than the 30-day historical data retention limit
`VALIDATION_ERROR`	`endTime is older than the 30-day historical data cap`	`endTime` is older than 30 days and `startTime` was not provided
`INVALID_FORMAT`	`invalid request format`	Malformed request body
`INTERNAL_ERROR`	`failed to get transfers`	Server error retrieving transfer data

Related Endpoints

Get Balance Updates - Deposit and withdrawal transaction history
Get Subaccount - View current account balances and margin status