---
title: "Core API client"
url: "https://platformdocs.coinme.com/#/docs/caas-core-api-client"
markdown: "https://platformdocs.coinme.com/docs/caas-core-api-client.md"
summary: "The `@coinme/core-api-client` package provides a client for interacting with the Coinme Core APIs, including authentication and data retrieval."
surface: "caas"
platform: "server"
package: "@coinme/core-api-client"
updated: "2026-11-04"
---

# Core API client

The `@coinme/core-api-client` package provides a client for interacting with the Coinme Core APIs, including authentication and data retrieval.

> **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.

> **This is version 2.0.0, and 1.x is deprecated.**
>
> This page documents version 2.0.0 of the CaaS API clients, which is not published yet; until it is, the registry serves 1.x, which is configured differently. Install with `@^2.0.0`. [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) covers installing, authenticating, environments and [upgrading from 1.x](https://platformdocs.coinme.com/docs/caas-api-clients.md#upgrading-from-1-x).

## Install

```bash
npm install @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 other client needs a token from this package's `AuthService`.

## AuthService

The AuthService class is responsible for managing authentication tokens. Each instance holds one partner's credentials for one environment, so several partners or environments can be served side by side. It ensures that only one token-fetching request is in progress at any given time. It also ensures that the token is valid and not expired. Server-only: it holds the partner client secret, so it refuses to run in a browser or React Native app. Mint a Transient Auth Token on your backend for anything that runs on a customer's device.

```typescript
import { AuthService } from '@coinme/core-api-client';

const authService = new AuthService({
  baseUrl: 'https://caas-staging.coinme.com/services',
  clientSecret: process.env.COINME_CLIENT_SECRET!,
  partnerId: process.env.COINME_PARTNER_ID!,
});
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `baseUrl` | `string` | Yes | Base URL of the CaaS API for the environment to authenticate against, including the `/services` path, for example `https://caas-staging.coinme.com/services`. |
| `clientSecret` | `string` | Yes | The client secret. Keep it on your server: it must never reach a browser or mobile app. |
| `partnerId` | `string` | Yes | The partner ID. |

### getToken

Returns a valid auth token (fetches a new one if expired or not available).

```typescript
getToken(): Promise<string>
```

Returns `Promise<string>`.

```typescript
const response = await authService.getToken();
```

## Create the client

The API client for interacting with Coinme Core APIs.

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

const coreClient = 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

### getCryptoChains

Retrieve the list of supported crypto currencies and their supported chains.

```typescript
getCryptoChains(query?: GetCryptoChainsQuery): Promise<GetCryptoChainsResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `query?` | `GetCryptoChainsQuery` | Optional filters, such as the jurisdiction. |

A promise that resolves to the list of supported crypto currencies and their supported chains as a `GetCryptoChainsResponse`. See [GetCryptoChainsResponse](#getcryptochainsresponse), [GetCryptoChainsQuery](#getcryptochainsquery).

```typescript
const response = await coreClient.getCryptoChains();
```

### getHistoricalData

Retrieve historical crypto market prices for a specified cryptocurrency over a certain period.

```typescript
getHistoricalData(queryParams: GetHistoricalDataQuery): Promise<GetHistoricalDataResponse>
```

| Parameter | Type | Description |
| --- | --- | --- |
| `queryParams` | `GetHistoricalDataQuery` | The query parameters needed for fetching the historical data. |

A promise that resolves to the historical data as a `GetHistoricalDataResponse`. See [GetHistoricalDataResponse](#gethistoricaldataresponse), [GetHistoricalDataQuery](#gethistoricaldataquery).

```typescript
const response = await coreClient.getHistoricalData({
  count: 1,
  currency: 'USD',
  fiat: 'fiat',
  interval: 'SECONDS',
});
```

### 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
coreClient.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.

### GetCryptoChainsQuery

Query for `GET /services/cryptoChains`: Get Supported Crypto Chains.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `jurisdiction` | `string` | No |  |

### GetCryptoChainsResponse

Response for `GET /services/cryptoChains`: Get Supported Crypto Chains.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cryptoChains` | `Record<string, { code?: string \| null; decimals?: number \| null; name?: string \| null; supportedChains?: string[] \| null }> \| null` | No |  |

### GetHistoricalDataQuery

Query for `GET /services/historiccryptodata`: Get Historical Crypto Market Data.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | `number` | Yes | Number of intervals |
| `currency` | `string` | Yes | Currency code of crypto (i.e. BTC, ETH) |
| `fiat` | `string` | Yes | Currency code of fiat (i.e. USD) |
| `interval` | `'SECONDS' \| 'MINUTES' \| 'HOURS' \| 'DAYS'` | Yes | The interval (SECONDS, MINUTES, HOURS, DAYS) |

### GetHistoricalDataResponse

Response for `GET /services/historiccryptodata`: Get Historical Crypto Market Data.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `object[] \| null` | No |  |
| `items[].close` | `string \| null` | No |  |
| `items[].high` | `string \| null` | No |  |
| `items[].low` | `string \| null` | No |  |
| `items[].open` | `string \| null` | No |  |
| `items[].timestamp` | `number \| null` | No |  |
| `items[].volume` | `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 };
```

### Other names

Names the package also exports for the types above. The 1.x names remain as aliases of the generated ones.

| Name | Same as |
| --- | --- |
| `GetHistoricalDataQueryParams` | `GetHistoricalDataQuery` |

## 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/core-api-client';

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