# TypeScript SDK — Account Services: Balances & Account

Account details, balances, roles, and account management. All methods are on `client.accountServices`.

See the [API specifications](/api-specifications) for full request/response schemas and the [authentication guide](/tools/typescript-sdk/authentication) for setup.

## Methods

### getAccountDetail

`POST /v1/account` · Authenticated

Returns details about the authenticated account including name, type, and associated users.

```ts
const detail = await client.accountServices.getAccountDetail({});

console.log(detail.account?.accountName); // e.g. "Primary"
console.log(detail.memo_reference_code);  // wire memo reference code
```

This is a POST mutation — never automatically retried. The empty object `{}` is required — the SDK adds transport fields (`nonce`, `request`) automatically.

### getAvailableBalances

`POST /v1/balances` · Authenticated

Returns the available balances for each currency in your account. The `account` field is **required** in the generated TypeScript type. The response is a bare array of `Balance` objects.

```ts
const balances = await client.accountServices.getAvailableBalances({
  account: "primary",
});

for (const entry of balances) {
  // entry.amount and entry.available are numbers, not strings
  console.log(`${entry.currency}: ${entry.available} available`);
}
```

> **Tip:** `amount` and `available` are **numbers** (not strings). Other fields like `availableForWithdrawal`, `pendingWithdrawal`, and `pendingDeposit` are also numbers. The `_timestamp` field is an ISO 8601 string for staleness detection — see [Data Types](/tools/typescript-sdk/deep-dives/data-types).

### getNotionalBalances

`POST /v1/notionalbalances/{currency}` · Authenticated

Returns balances denominated in the specified fiat currency. Uses the `{ path, body }` input pattern because the currency is a URL path parameter.

```ts
const balances = await client.accountServices.getNotionalBalances({
  path: { currency: "usd" },
  body: {},
});

for (const entry of balances) {
  console.log(`${entry.currency}: ${entry.amountNotional} USD`);
}
```

> **Tip:** The `path.currency` selects the denomination (e.g. `"usd"`, `"gbp"`, `"eur"`). Notional values (`amountNotional`, `availableNotional`, `availableForWithdrawalNotional`) are decimal strings.

### getRoles

`POST /v1/roles` · Authenticated

Returns the roles assigned to the API key making the request.

```ts
const roles = await client.accountServices.getRoles({});
console.log(roles.isTrader);       // boolean
console.log(roles.isFundManager);  // boolean
console.log(roles.isAuditor);      // boolean
```

### listAccountsInGroup

`POST /v1/account/list` · Authenticated

Lists all accounts in the master group. Useful for multi-account setups. The response is a bare array.

```ts
const accounts = await client.accountServices.listAccountsInGroup({});

for (const acct of accounts) {
  console.log(`${acct.name} (${acct.account}) — ${acct.status}`);
}
```

> **Tip:** The `timestamp` field in the request body accepts `bigint` or `number`.

### createNewAccount

`POST /v1/account/create` · Authenticated

Creates a new sub-account within your account group. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation).

```ts
const result = await client.accountServices.createNewAccount({
  name: "strategy-2",
  type: "exchange",
});

console.log(result.account); // e.g. "strategy-2"
console.log(result.type);    // "exchange" or "custody"
```

This is a POST mutation — never automatically retried. Account creation is idempotent by name — creating an account with an existing name returns the existing account.

### renameAccount

`POST /v1/account/rename` · Authenticated

Renames a sub-account. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation) — the SDK checks field types before sending.

```ts
const result = await client.accountServices.renameAccount({
  account: "my-account",
  newName: "primary-trading",
});
```

This is a POST mutation — never automatically retried. If the request fails mid-flight you should confirm the rename status before retrying.

## What's next

- [Addresses & Deposits](/tools/typescript-sdk/reference/account-services/addresses-and-deposits) — deposit addresses and approved address management
- [Withdrawals & Transfers](/tools/typescript-sdk/reference/account-services/withdrawals-and-transfers) — moving funds out or between accounts
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — why balances are numbers and timestamps may be bigint
- [Error Handling](/tools/typescript-sdk/errors) — handling API errors