---
title: "Custody API client"
url: "https://platformdocs.coinme.com/#/docs/caas-custody-api-client"
markdown: "https://platformdocs.coinme.com/docs/caas-custody-api-client.md"
summary: "The `@coinme/custody-api-client` package provides a client for interacting with the Coinme custody APIs: customer wallets, sends to external wallets, and the partner's own (enterprise) balances. It covers the custody operations in one client."
surface: "caas"
platform: "server"
package: "@coinme/custody-api-client"
updated: "2026-11-04"
---

# Custody API client

The `@coinme/custody-api-client` package provides a client for interacting with the Coinme custody APIs: customer wallets, sends to external wallets, and the partner's own (enterprise) balances. It covers the custody operations in one client. `send` is also available from `@coinme/send-api-client`, which stays published for existing integrations.

> **Server only.**
>
> `AuthService` takes your partner client secret and mints a partner access token. Use it, and these clients, only on your backend (Node.js). Never bundle them into a browser, WebView or mobile (React Native) app, where anyone can extract the secret and the token: `AuthService` throws if it runs there. For anything that runs on a customer's device, mint a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) on your backend instead.

> **Not published yet, and new with version 2.0.0.**
>
> This package is new with version 2.0.0 of the CaaS API clients and is published in the same release as version 0.1.0, so install it with `@^0.1.0` rather than `@^2.0.0`. The 1.x clients are deprecated. [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) covers installing, authenticating and choosing an environment.

## Install

```bash
npm install @coinme/custody-api-client@^0.1.0 @coinme/core-api-client@^2.0.0
```

The packages come from Coinme's private registry; [Install in the overview](https://platformdocs.coinme.com/docs/caas-api-clients.md#install) shows the `.npmrc` entries. Every client needs a token from `AuthService` in `@coinme/core-api-client`.

## Create the client

The API client for the Coinme custody APIs: customer wallets, sends to external wallets, and the partner's own (enterprise) balances.

```typescript
import { APIClient } from '@coinme/custody-api-client';

const custodyClient = new APIClient({
  baseUrl: 'https://caas-staging.coinme.com/services',
  partnerId: process.env.COINME_PARTNER_ID!,
  token: await authService.getToken(),
});
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `baseUrl` | `string` | Yes | Base URL of the CaaS API for the environment to call, including the `/services` path, for example `https://caas-staging.coinme.com/services` for staging. Use the URLs Coinme provides for each environment. |
| `partnerId` | `string` | Yes | The unique identifier Coinme assigns to each partner. |
| `token` | `string` | Yes | The bearer token from `AuthService.getToken()`. |

A client keeps the token it was given; pass a new one to `updateToken` when it expires, or create the client per request. [Environments in the overview](https://platformdocs.coinme.com/docs/caas-api-clients.md#environments) lists the base URLs.

## Methods

### createWallet

Creates a wallet that a customer can receive a currency into, or returns the existing one.

```typescript
createWallet(query: CreateWalletQuery): Promise<CreateWalletResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | `CreateWalletQuery` | The customer and the currency (asset id) of the wallet. |

A promise that resolves to the `CreateWalletResponse`. See [CreateWalletResponse](#createwalletresponse), [CreateWalletQuery](#createwalletquery).

```typescript
const response = await custodyClient.createWallet({
  currency: 'USD',
  customerId: 'customer-id',
});
```

### estimateFee

Estimates the network (blockchain) fee of sending a currency from a customer's Coinme wallet.

```typescript
estimateFee(query: EstimateFeeQuery): Promise<EstimateFeeResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | `EstimateFeeQuery` | The customer, the currency and optionally the chain. |

A promise that resolves to the `EstimateFeeResponse`. See [EstimateFeeResponse](#estimatefeeresponse), [EstimateFeeQuery](#estimatefeequery).

```typescript
const response = await custodyClient.estimateFee({
  currencySymbol: 'currency-symbol',
  customerId: 'customer-id',
});
```

### getEnterpriseBalance

Returns the partner's own (enterprise) wallet balance of one asset, net of pending sends.

```typescript
getEnterpriseBalance(asset: string): Promise<GetEnterpriseBalanceResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `asset` | `string` | The asset id, for example `USDC/XLM`. |

A promise that resolves to the `GetEnterpriseBalanceResponse`. See [GetEnterpriseBalanceResponse](#getenterprisebalanceresponse).

```typescript
const response = await custodyClient.getEnterpriseBalance('asset');
```

### getEnterpriseBalances

Returns the partner's own (enterprise) wallet balances, one per asset.

```typescript
getEnterpriseBalances(): Promise<GetEnterpriseBalancesResponse>
```

A promise that resolves to the `GetEnterpriseBalancesResponse`. See [GetEnterpriseBalancesResponse](#getenterprisebalancesresponse).

```typescript
const response = await custodyClient.getEnterpriseBalances();
```

### getWallets

Returns the wallet addresses of a customer: one per currency and chain.

```typescript
getWallets(query: GetWalletsQuery): Promise<GetWalletsResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | `GetWalletsQuery` | The customer. |

A promise that resolves to the `GetWalletsResponse`. See [GetWalletsResponse](#getwalletsresponse), [GetWalletsQuery](#getwalletsquery).

```typescript
const response = await custodyClient.getWallets({
  customerId: 'customer-id',
});
```

### send

Sends a specified amount of crypto from a customer's wallet to an external wallet address.

```typescript
send(body: SendRequest): Promise<SendResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `body` | `SendRequest` | The customer, destination, amount and currency. |

A promise that resolves to the `SendResponse`. See [SendResponse](#sendresponse), [SendRequest](#sendrequest).

```typescript
const response = await custodyClient.send({
  amount: '100',
  currency: 'USD',
  customerId: 'customer-id',
  destinationWalletAddress: 'destination-wallet-address',
});
```

### sendAll

Sends a customer's entire available balance of an asset to an external wallet address.

```typescript
sendAll(body: SendAllRequest): Promise<SendAllResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `body` | `SendAllRequest` | The customer, destination and asset. |

A promise that resolves to the `SendAllResponse`. See [SendAllResponse](#sendallresponse), [SendAllRequest](#sendallrequest).

```typescript
const response = await custodyClient.sendAll({
  assetId: 'asset-id',
  customerId: 'customer-id',
  destinationWalletAddress: 'destination-wallet-address',
});
```

### updateToken

Allows updating the token dynamically (e.g., after refresh), without creating a new instance of the client.

```typescript
updateToken(newToken: string): void
```

| Parameter | Type | Description |
| --- | --- | --- |
| `newToken` | `string` | The new token to use. |

Returns `void`.

```typescript
custodyClient.updateToken('new-token');
```

## Types

The request, query and response types of the methods above, as the package exports them. Ids are strings and amounts are decimal strings, as the API sends and expects them; response fields are optional and may be null, because the API leaves out or nulls values it has no data for.

### CreateWalletQuery

Query for `POST /services/wallets`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `correlationId` | `string` | No |  |
| `currency` | `string` | Yes |  |
| `customerId` | `string` | Yes |  |

### CreateWalletResponse

Response for `POST /services/wallets`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | `string \| null` | No |  |
| `address` | `string \| null` | No |  |
| `currencyName` | `string \| null` | No |  |
| `currencySymbol` | `string \| null` | No |  |
| `walletAddress` | `string \| null` | No |  |
| `walletId` | `string \| null` | No |  |

### EstimateFeeQuery

Query for `GET /services/wallets/estimateFee`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | `string` | No | The crypto chain identifier to estimate the fee on (e.g. ETH, SOL). Must match supported chains returned by /services/cryptoChains. Not needed if using full assetId in currencySymbol |
| `currencySymbol` | `string` | Yes | Symbol of the crypto asset you’re sending on that chain (e.g. ETH, USDT, USDC, BTC). Partners also have the option to use full asset ID (e.g. USDT_SOL, USDC_POL, etc) |
| `customerId` | `string` | Yes | Unique customer identifier |

### EstimateFeeResponse

Response for `GET /services/wallets/estimateFee`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `estimateFee` | `string \| null` | No | Estimated network fee denominated in the crypto asset identified by currencySymbol (e.g. 0.00042 ETH). |
| `estimateFeeUSD` | `string \| null` | No | Same fee converted to USD |

### GetEnterpriseBalanceResponse

Response for `GET /services/enterprise/wallets/balance/{asset}`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `balances` | `object[] \| null` | No |  |
| `balances[].assetId` | `string \| null` | No |  |
| `balances[].availableBalance` | `string \| null` | No |  |
| `balances[].chain` | `string \| null` | No |  |
| `balances[].currencySymbol` | `string \| null` | No |  |

### GetEnterpriseBalancesResponse

Response for `GET /services/enterprise/wallets/balance`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `balances` | `object[] \| null` | No |  |
| `balances[].assetId` | `string \| null` | No |  |
| `balances[].availableBalance` | `string \| null` | No |  |
| `balances[].chain` | `string \| null` | No |  |
| `balances[].currencySymbol` | `string \| null` | No |  |

### GetWalletsQuery

Query for `GET /services/wallets`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customerId` | `string` | Yes | Unique customer identifier |

### GetWalletsResponse

Response for `GET /services/wallets`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `walletAddresses` | `object[] \| null` | No |  |
| `walletAddresses[].assetId` | `string \| null` | No |  |
| `walletAddresses[].chain` | `string \| null` | No |  |
| `walletAddresses[].currencyName` | `string \| null` | No |  |
| `walletAddresses[].currencySymbol` | `string \| null` | No |  |
| `walletAddresses[].walletAddress` | `string \| null` | No |  |

### SendAllRequest

Request for `POST /services/send-all`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `assetId` | `string` | Yes |  |
| `blockchainTag` | `string` | No |  |
| `customerId` | `string` | Yes |  |
| `destinationWalletAddress` | `string` | Yes |  |
| `note` | `string` | No |  |
| `partnerTransactionId` | `string` | No |  |
| `rampId` | `string` | No |  |

### SendAllResponse

Response for `POST /services/send-all`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `partnerTransactionId` | `string \| null` | No |  |

### SendRequest

Request for `POST /services/send`: Initiate a Send Transaction.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `string` | Yes | Amount of crypto to send |
| `blockchainTag` | `string` | No | Additional wallet identifier |
| `cryptoChain` | `string` | No | Chain over which to send the asset (i.e. ETH, XLM) |
| `currency` | `string` | Yes | Currency of the amount to send (i.e. BTC) |
| `customerId` | `string` | Yes | Unique customer identifier |
| `destinationWalletAddress` | `string` | Yes | Destination wallet address |
| `note` | `string` | No | Additional transaction information |
| `partnerTransactionId` | `string` | No | Id of the transaction. If the partnerTransactionId is not sent then it will be generated by Coinme and sent back in the response |
| `rampId` | `string` | No |  |

### SendResponse

Response for `POST /services/send`: Initiate a Send Transaction.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `partnerTransactionId` | `string \| null` | No |  |

### Nullable

A type that represents a nullable version of the given type.

```typescript
type Nullable<T> = { [P in keyof T]: T[P] | null };
```

## Errors

Every method rejects with an `APIError` when a call fails. Check for it with `isAPIError`, which works across packages, rather than `instanceof`. [Errors in the overview](https://platformdocs.coinme.com/docs/caas-api-clients.md#errors) explains the error shape.

| Export | What it is |
| --- | --- |
| `APIError` | Custom error class for handling API responses. Extends the native Error class to include structured error response details. |
| `isAPIError` | Tells whether an error was thrown by a CaaS API client. Prefer this to `instanceof APIError` when an application uses more than one client package: each package carries its own copy of the class. |
| `CAASErrorData` | Represents detailed information about an individual error in a CAAS error response. |
| `CAASErrorResponse` | Represents the structure of a CAAS error response, including HTTP status, timestamp, path, and an array of individual error data. |
| `GenericErrorResponse` | Represents the structure of a generic error response, used when handling non-CAAS errors like client or server errors (4xx or 5xx). |

### CAASErrorResponse

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `caasError` | `boolean` | Yes | True when the response body carried the CaaS error envelope (`errorResponse.errorData`), whatever the HTTP status; `errorData` then holds the server's own error codes. False for network failures and other error bodies, which are reported as one `GENERIC_ERROR`. |
| `errorData` | `CAASErrorData<U, V>[]` | Yes | Array of detailed error information objects, each representing an individual error. For non-CAAS errors, this array may contain generic error data. |
| `httpStatus` | `string` | Yes | HTTP status code as a string, indicating the type of error response. |
| `path` | `string` | Yes | API path where the error occurred, useful for tracing the origin of the error. |
| `timestamp` | `string` | Yes | Timestamp when the error occurred, in ISO 8601 format. |

### CAASErrorData

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `errorCode` | `U` | Yes | Unique code identifying the specific error that occurred. |
| `message` | `string` | Yes | Descriptive message explaining the nature of the error. |
| `metadata` | `V` | No | Optional metadata providing additional context for the error. |

```typescript
import { isAPIError } from '@coinme/custody-api-client';

try {
  // a call on the client
} catch (error) {
  if (isAPIError(error)) {
    console.error(error.errorResponse.httpStatus, error.errorResponse.errorData);
  }
  throw error;
}
```
