Update Subaccount Name

Rename an existing trading subaccount. The authenticated subaccount's display name is updated to the new value provided in the request.

Endpoint

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

Request

Request Format

{
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Scalping Strategy"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Parameters object containing action details
`params.action`	string	Yes	Must be `"updateSubAccountName"`
`params.subAccountId`	string	Yes	Subaccount identifier to rename
`params.name`	string	Yes	New display name for the subaccount
`nonce`	integer (uint64)	Yes	Unix milliseconds timestamp, monotonically increasing
`signature`	object	Yes	EIP-712 signature object
`expiresAfter`	integer	No	Expiration timestamp in seconds

EIP-712 Type Definition

const UpdateSubAccountNameTypes = {
  UpdateSubAccountName: [
    { name: "subAccountId", type: "uint256" },
    { name: "name", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "expiresAfter", type: "uint256" }
  ]
}

Response

Success Response

{
  "status": "ok",
  "response": {
    "subAccountId": "1867542890123456789",
    "name": "Scalping Strategy"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Response Fields

Field	Type	Description
`subAccountId`	string	Subaccount identifier that was renamed
`name`	string	The new display name that was applied

Error Response

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

Common Error Cases

{
  "status": "error",
  "error": {
    "message": "Invalid request body",
    "code": "INVALID_FORMAT"
  },
  "request_id": "5ccf215d37e3ae6d"
}

{
  "status": "error",
  "error": {
    "message": "Subaccount not found",
    "code": "NOT_FOUND"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Code Examples

Rename Subaccount

{
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Main Trading"
  },
  "nonce": 1704067200000,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067300
}

Rename to Strategy-Based Name

{
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Grid Trading Bot"
  },
  "nonce": 1704067200001,
  "signature": {
    "v": 28,
    "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "s": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "expiresAfter": 1704067301
}

Validation Rules

nonce must be a timestamp in milliseconds and must be increasing
name must be a valid string
subAccountId must reference an existing subaccount owned by the signer
Must be signed by account owner or authorized delegate
Name must not already be in use by another subaccount under the same wallet

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

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	Description
subAccountId is required	No subaccount was specified in the request
Invalid request body	Request payload could not be parsed
Subaccount not found	The specified subaccount does not exist
Name already in use	Another subaccount already uses this name
Failed to update subaccount	Internal error during the update operation