Update Subaccount Name (WebSocket)

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

Endpoint

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

Request

Request Format

{
  "id": "rename-subaccount-1",
  "method": "post",
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Scalping Strategy",
    "nonce": 1704067200000,
    "expiresAfter": 1704067300,
    "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 Fields

Parameter	Type	Required	Description
`action`	string	Yes	Must be `"updateSubAccountName"`
`subAccountId`	string	Yes	Subaccount identifier to rename
`name`	string	Yes	New display name for the subaccount
`nonce`	integer	Yes	Incrementing nonce (Unix ms timestamp as number)
`expiresAfter`	integer	No	Optional expiration timestamp in seconds (0 = no expiration)
`signature`	object	Yes	EIP-712 signature

EIP-712 Type Definition

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

Response Format

Success Response

{
  "id": "rename-subaccount-1",
  "requestId": "rename-subaccount-1",
  "status": 200,
  "timestamp": 1704067200123,
  "result": {
    "status": "success",
    "response": {
      "subAccountId": "1867542890123456789",
      "name": "Scalping Strategy"
    }
  }
}

Response Fields:

Field	Type	Description
`id`	string	Echo of the client-provided request identifier
`requestId`	string	Same value as `id` (included for forward compatibility)
`status`	integer	HTTP status code
`timestamp`	integer	Server timestamp in milliseconds (Unix epoch)
`result.status`	string	`"success"` on successful requests
`result.response.subAccountId`	string	Subaccount identifier that was renamed
`result.response.name`	string	The new display name that was applied

Error Response

{
  "id": "rename-subaccount-1",
  "requestId": "rename-subaccount-1",
  "status": 400,
  "timestamp": 1704067200456,
  "error": {
    "code": 400,
    "errorCode": "VALIDATION_ERROR",
    "category": "REQUEST",
    "message": "subAccountId is required",
    "retryable": false
  }
}

Implementation Example

import { ethers } from 'ethers';
 
async function updateSubAccountName(ws, signer, subAccountId, name) {
  const nonce = Date.now();
  const expiresAfter = Math.floor(Date.now() / 1000) + 30;
 
  const domain = {
    name: "Synthetix",
    version: "1",
    chainId: 1,
    verifyingContract: "0x0000000000000000000000000000000000000000"
  };
 
  const types = {
    UpdateSubAccountName: [
      { name: "subAccountId", type: "uint256" },
      { name: "name", type: "string" },
      { name: "nonce", type: "uint256" },
      { name: "expiresAfter", type: "uint256" }
    ]
  };
 
  const message = {
    subAccountId: BigInt(subAccountId),
    name,
    nonce: BigInt(nonce),
    expiresAfter: BigInt(expiresAfter)
  };
 
  const sig = await signer.signTypedData(domain, types, message);
  const signature = ethers.Signature.from(sig);
 
  ws.send(JSON.stringify({
    id: `rename-subaccount-${Date.now()}`,
    method: "post",
    params: {
      action: "updateSubAccountName",
      subAccountId,
      name,
      nonce,
      expiresAfter,
      signature: { v: signature.v, r: signature.r, s: signature.s }
    }
  }));
}
 
// Usage: Rename a subaccount
await updateSubAccountName(ws, signer, "1867542890123456789", "Grid Trading Bot");

Code Examples

Rename Subaccount

{
  "id": "rename-1",
  "method": "post",
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Main Trading",
    "nonce": 1704067200000,
    "expiresAfter": 1704067300,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Rename to Strategy-Based Name

{
  "id": "rename-2",
  "method": "post",
  "params": {
    "action": "updateSubAccountName",
    "subAccountId": "1867542890123456789",
    "name": "Grid Trading Bot",
    "nonce": 1704067200001,
    "expiresAfter": 1704067301,
    "signature": { "v": 28, "r": "0x...", "s": "0x..." }
  }
}

Error Handling

Common Errors

Error Code	Message	Description
400	subAccountId is required	No subaccount was specified
400	Invalid request body	Request payload could not be parsed
400	Name already in use	Another subaccount already uses this name
404	Subaccount not found	The specified subaccount does not exist

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 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 Subaccount - Verify the name change
Create Subaccount - Create a new subaccount
REST Alternative - REST API comparison