---
title: "CaaS API clients"
url: "https://platformdocs.coinme.com/#/docs/caas-api-clients"
markdown: "https://platformdocs.coinme.com/docs/caas-api-clients.md"
summary: "The CaaS API clients are typed TypeScript packages for calling the Coinme-as-a-Service (CAAS) API from your backend. Each package wraps one area of the API, so instead of building requests by hand you call a method such as `getTransactionalQuote` or `send`, and you get back typed data or a typed error."
surface: "caas"
platform: "server"
updated: "2026-11-04"
---

# CaaS API clients

The CaaS API clients are typed TypeScript packages for calling the Coinme-as-a-Service (CAAS) API from your backend. Each package wraps one area of the API, so instead of building requests by hand you call a method such as `getTransactionalQuote` or `send`, and you get back typed data or a typed error.

> **A new version is on the way, and 1.x is deprecated.**
>
> The CaaS API clients are being updated to version 2.0.0, and the existing 1.x versions are deprecated: do not start a new integration on them, and plan to move an existing one. This page describes 2.0.0. Until it is published, the registry still serves 1.x, which takes its configuration differently and does not match the examples here, so install with `@^2.0.0` as shown under Install rather than taking whatever version is latest. [Upgrading from 1.x](https://platformdocs.coinme.com/docs/caas-api-clients.md#upgrading-from-1-x) lists what changes.

## Why use them

The CAAS API is a REST API you can call from any language. The clients exist for teams whose backend runs on Node.js and who would otherwise write and maintain the same plumbing for every endpoint. They handle the parts that are easy to get subtly wrong: exchanging your partner credentials for a bearer token and fetching a new one once it expires, sending the partner and token headers on every call, encoding path and query values, sending the requests that carry identity data to their own secure host, and turning both transport failures and API error bodies into one error shape.

Their request and response types follow the API itself. They are generated from the same sources as the API reference and the services behind it, so a field the API reads is a field the types know about, with the type the API expects.

## Where they run

The clients run in your backend. They give it convenience methods for every CaaS call, and they make a natural foundation for a backend-for-frontend: the service your web or mobile app talks to, which calls CaaS through the clients and shapes the results for your screens. `AuthService` holds your client secret, so the clients live on the server side of that boundary, and your front ends reach CaaS through your backend. `AuthService` enforces this: its constructor throws an `Error` when it runs in a browser (a WebView or an Electron renderer included) or in React Native, before any request is sent, so the secret and the token never reach a customer's device. For anything that runs on a device, your backend mints a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) instead. Use Node.js 24.22.1 or later, or 22.23.4 or later in the 22.x line: earlier versions have known security vulnerabilities, and from 2.0.0 the packages declare this in `engines`.

## Packages

| Package | What it covers | Reference |
| --- | --- | --- |
| `@coinme/core-api-client` | Authentication (`AuthService`), supported crypto currencies and their chains, historical market data | [Methods and types](https://platformdocs.coinme.com/docs/caas-core-api-client.md) |
| `@coinme/prove-onboarding-api-client` | Phone verification (mobile auth and instant link), identity prefill and verification, customer onboarding | [Methods and types](https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md) |
| `@coinme/quotes-api-client` | Transactional and informational quotes, transaction limits | [Methods and types](https://platformdocs.coinme.com/docs/caas-quotes-api-client.md) |
| `@coinme/transactions-api-client` | Buy and sell, with or without a quote, sell all, and submitting the blockchain id of a sell funded from an external wallet | [Methods and types](https://platformdocs.coinme.com/docs/caas-transactions-api-client.md) |
| `@coinme/history-api-client` | Asset balances, transaction history, a single transaction | [Methods and types](https://platformdocs.coinme.com/docs/caas-history-api-client.md) |
| `@coinme/locations-api-client` | The jurisdictions Coinme is licensed in | [Methods and types](https://platformdocs.coinme.com/docs/caas-locations-api-client.md) |
| `@coinme/send-api-client` | Sending to an external wallet | [Methods and types](https://platformdocs.coinme.com/docs/caas-send-api-client.md) |
| `@coinme/custody-api-client` | Not yet published. Customer wallets, network fee estimates, sends to external wallets, and your own enterprise balances | [Methods and types](https://platformdocs.coinme.com/docs/caas-custody-api-client.md) |
| `@coinme/cash-ramp-api-client` | Not yet published. Cash locations and order templates, the barcodes customers present at a location | [Methods and types](https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md) |

Each package has its own reference page, listed above, with every method, its parameters, an example and every request and response type. Install only the packages for the parts of the API you use. Every client needs a token from `AuthService`, which lives in `@coinme/core-api-client`, so that package is always one of them.

The custody and cash ramp clients are new with 2.0.0 and are published in the same release, but as version 0.1.0, so install them with `@^0.1.0` rather than `@^2.0.0`. Until that release they are not on the registry. When the custody client is out it covers sends along with the rest of custody; `@coinme/send-api-client` stays published for the integrations that use it.

## Install

The packages are published to Coinme's private npm registry at `https://npm.coinme.com/coinme-caas/`. Ask your Coinme integration contact for a token that can read it, then point the `@coinme` scope at the registry in your project's `.npmrc`, reading the token from an environment variable:

```bash
@coinme:registry=https://npm.coinme.com/coinme-caas/
//npm.coinme.com/coinme-caas/:_authToken=${COINME_CAAS_REGISTRY_TOKEN}
```

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

Keep the token in your environment or CI secrets, never in a committed `.npmrc`.

## Authenticate

`AuthService` exchanges your partner ID and client secret for a bearer token, caches it, and fetches a new one once it expires. Create one per partner and environment when your server starts, and reuse it.

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

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

Keep the client secret in your backend's secret store, out of source control and out of anything you ship to a browser or a device. Tests that create an `AuthService` in a browser-like environment such as jsdom or happy-dom throw for the same reason; run them in the `node` environment.

## Call the API

Every package exports an `APIClient` that takes your partner ID, a token and the base URL of the environment to call. Its methods mirror the API's operations.

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

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

const quote = await quotes.createBuyTransactionalQuote({
  customerId: 'customer-id',
  debitCurrencyCode: 'USD',
  creditCurrencyCode: 'BTC',
  amountValue: '100',
  amountCurrencyCode: 'USD',
});
```

A client keeps the token it was given. When the token expires, ask the same `AuthService` for a new one and pass it to `updateToken` on each client you keep, or create the clients per request.

## Environments

Nothing about the environment is fixed when the packages are built: every client and `AuthService` takes the base URL to call, including the `/services` path. Staging is `https://caas-staging.coinme.com/services` and production is `https://caas.coinme.com/services`. Because the URL is a parameter, one installation can call staging and production side by side, for example from separate test and live configurations. A client or `AuthService` created without a base URL throws a `TypeError` straight away rather than on its first call.

Customer onboarding goes to its own secure host because it sends the customer's identity details, so `@coinme/prove-onboarding-api-client` also takes an `onboardingBaseUrl`. It includes the `/services` path, and every other call in that package uses `baseUrl`. Ask your Coinme integration contact for the URL for each environment.

## Errors

Every method rejects with an `APIError` when a call fails. Its `errorResponse` holds the HTTP status, the API path and `errorData`, a list of error codes with messages. When the API answered with its own error body, `errorResponse.caasError` is `true` and `errorData` carries the API's error codes, whatever the HTTP status. Network failures and other errors arrive as a single `GENERIC_ERROR` entry.

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

try {
  await quotes.getTransactionalQuote('quote-id');
} catch (error) {
  if (isAPIError(error)) {
    console.error(error.errorResponse.httpStatus, error.errorResponse.errorData);
  }
  throw error;
}
```

Check errors with `isAPIError` rather than `instanceof APIError` when you use more than one package, because each package carries its own copy of the class.

## Types

Each package exports the request, query and response types of its operations, named after the operation: `CreateTransactionalQuoteRequest`, `GetTransactionHistoryQuery`, `GetTransactionResponse` and so on. Identifiers such as `customerId` and `partnerTransactionId` 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.

## Upgrading from 1.x

2.0.0 changes how the clients are configured and corrects their types, so 1.x code needs these changes:

- `AuthService.getInstance({ partnerId, clientSecret })` becomes `new AuthService({ partnerId, clientSecret, baseUrl })`. Each instance holds one partner's credentials for one environment; the 1.x singleton silently ignored credentials passed after the first call.
- Every `new APIClient({ partnerId, token })` also takes `baseUrl`. 1.x read the API host when the package was built, so one installation could only call one environment.
- `@coinme/prove-onboarding-api-client` also takes `onboardingBaseUrl`.
- Ids are strings everywhere: `partnerTransactionId`, `paymentMethodId` and `webSessionId` no longer accept numbers, and `tags` is a `string[]`. Amounts such as `amountValue` are decimal strings.
- For `buy` and `sell` in `@coinme/transactions-api-client`, `quoteInput.providerId` is required.
- In `@coinme/history-api-client`, `getAssetBalances` takes `estimatedBalanceCurrencyCode` instead of `currencyCode`, and `getTransaction` resolves to `{ transaction }`.
- In `@coinme/prove-onboarding-api-client`, customer onboarding's `phoneNumber` is `{ countryCode, number }`, `fullName.otherNames` is a `string[]`, and `getInstantLinkById` resolves to `{ redirectUrl }`.
- A successful response without a body resolves to `undefined` instead of failing.
- `AuthService` throws when it is created in a browser, a WebView, an Electron renderer or React Native. Move any such code to your backend, and run tests that create one in the `node` environment.

The 1.x type names remain as aliases of the new ones, for example `SendBodyParams` is `SendRequest`, so most type imports keep working.

## Where to go next

The [API reference](https://docs.coinme.com/reference) on docs.coinme.com describes every operation the clients call, and the [getting started guide](https://docs.coinme.com/docs/getting-started) walks through a first integration end to end. Each package ships a README that lists its methods with an example.
