Transfer Collateral

Transfer collateral between subaccounts. The signing wallet must be authorized (as owner or manager) for both the source and the destination subaccount.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "transferCollateral",
    "subAccountId": "1867542890123456789",
    "destinationSubAccountId": "1867542890123456790",
    "symbol": "USDT",
    "amount": "500.00"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Parameters object containing method details
`params.action`	string	Yes	Must be `"transferCollateral"`
`params.subAccountId`	string	Yes	Source subaccount identifier
`params.destinationSubAccountId`	string	Yes	Destination subaccount identifier
`params.symbol`	string	Yes	Collateral asset symbol (e.g., `"USDT"`)
`params.amount`	string	Yes	Amount to transfer as a decimal string (e.g., `"500.00"`)
`nonce`	integer (uint64)	Yes	Positive integer, incrementing nonce
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	integer	No	Expiration timestamp in Unix milliseconds (optional)

Authorization

The signing wallet must be authorized as owner or manager for both the source (subAccountId) and destination (destinationSubAccountId) subaccounts. Transfers to subaccounts for which the signer is not authorized are rejected.

Delegate wallets cannot initiate collateral transfers.

EIP-712 Signing

The amount field is included in the EIP-712 typed data exactly as provided in the request (wire format). Decimal strings without a leading zero (e.g., ".1") are accepted and verified against the original wire format.

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

Success Response

{
  "status": "ok",
  "response": {},
  "request_id": "5ccf215d37e3ae6d"
}

Error Response

{
  "status": "error",
  "error": {
    "message": "not the owner or manager of this subaccount",
    "code": "UNAUTHORIZED"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Common Errors

Error	Description
`not the owner or manager of this subaccount` (HTTP 401)	Signing wallet is not authorized for the source or destination subaccount
Insufficient balance	Source subaccount does not have enough collateral of the specified asset
Margin requirement violation	Transfer would leave source subaccount under margin requirements
Invalid asset symbol	Specified asset is not a supported collateral type

Implementation Notes

Signing wallet must have owner or manager authorization on both source and destination subaccounts
amount must conform to the asset's QuantityPrecision; query POST /v1/info (getAssets) for the allowed precision
EIP-712 signature is verified against the exact wire-format amount string provided in the request

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

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

Withdraw Collateral — Withdraw collateral to an external wallet
Get Subaccount — Check current balances and authorization
Get Balance Updates — View transfer history