---
name: coinme-caas-api-clients
description: "Call the Coinme-as-a-Service API from a Node.js backend with version 2 of the typed @coinme CaaS API clients: install 2.x from the private registry, create one AuthService per partner and environment, construct the client for each area of the API with the environment base URL, and handle APIError. Use when asked to integrate Coinme CaaS, CAAS or Coinme-as-a-Service onboarding, quotes, transactions or history into a server, or to move an integration off the deprecated 1.x clients."
metadata:
  surface: "caas"
  package: "@coinme/core-api-client"
---

# Coinme CaaS API clients on a Node.js server

## When to use this skill

The human's Node.js backend needs to call the Coinme-as-a-Service API, either directly or as the backend-for-frontend their web or mobile app talks to. The clients belong in that backend: for a front-end feature, add the CaaS calls to the backend the front end calls and use the clients there.

## Which integration this is

This skill is for the **Coinme-as-a-Service (CaaS) integration**: the partner keeps its own users and its own screens, and Coinme performs regulated services for them (onboarding and KYC, card vaulting, risk signals, transactions). The users are the partner's customers, not Coinme users. There is no Coinme Widget here, so no `rampId`, `partnerKey`, widget URL or embed allowlist. If the human wants to embed the Coinme Widget instead, this is the wrong skill: read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and pick a Widget skill.

## What you will produce

A server module that creates one AuthService per partner and environment at startup, constructs the API clients the integration needs with that environment base URL (plus the secure onboarding host where the guide requires it), and wraps calls so APIError is handled with isAPIError, with every credential read from configuration.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `COINME_CAAS_REGISTRY_TOKEN` | Read-only token for the registry that serves the CaaS API clients, https://npm.coinme.com/coinme-caas/. The token for the Coinme web and mobile SDKs does not read it. | An environment variable read by the project .npmrc at install time; CI reads it from a secret. Never in a committed file. |
| `partnerId and clientSecret` | The partner credentials AuthService exchanges for a bearer token. One pair per environment. | The server's secret store or environment variables, read at startup. Never in source, a browser bundle or a mobile app. |
| `baseUrl and onboardingBaseUrl` | The CaaS API base URL of each environment, and the secure host customer onboarding goes to. | Server configuration per environment, next to the credentials of that environment. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- Samples show the environment (such as `'sandbox'`, `'test'` or a staging base URL) as a literal so each stays self-contained. In the project, read it from the runtime configuration the human's build uses (for Vite, `VITE_*` variables in a gitignored `.env.local` with a committed `.env.example`), with a value per environment.
- This integration has no `rampId`, `partnerKey`, widget URL or embed allowlist. Do not ask for them or add them; they belong to the Widget skills.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

Put the clients in the backend, for example a backend-for-frontend that the web or mobile app calls: AuthService holds the client secret, so it stays server-side and the front end reaches CaaS through the backend. AuthService throws if it is created in a browser, WebView, Electron renderer or React Native app; never import the clients into client code, and run any test that creates an AuthService in the `node` environment, not jsdom or happy-dom.

Install only the packages for the parts of the API the integration uses; @coinme/core-api-client is always one of them, for AuthService.

Version 1.x is deprecated and configured differently (AuthService.getInstance, no baseUrl). Pin every package to ^2.0.0; if 2.0.0 is not on the registry yet, stop and tell the human rather than falling back to 1.x.

The custody and cash ramp clients are not published yet; they publish with the 2.0.0 release as version 0.1.0, so pin them to ^0.1.0, not ^2.0.0. Until they are on the registry, do not add them; use @coinme/send-api-client for sends.

Each package has a reference page with every method, its parameters, a type-checked example and every request and response type: docs/caas-<package>.md beside this skill in llms.txt, for example docs/caas-quotes-api-client.md. Read the page for each package before calling it rather than guessing field names.

## Procedure

Follow the guide below in order. It is the integration guide for this platform as published, so the section names are the guide's own.

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

## Verify

Run the server against staging. Confirm AuthService obtains a token, that one read call (for example getCryptoChains from @coinme/core-api-client) succeeds, that a deliberately invalid call rejects with an APIError that isAPIError recognises, and that no secret, token or registry token is in a committed file or in any client-side bundle.

### Reading the result

**Done when:** The client authorises, and each call you added resolves with data rather than rejecting with an `APIError`.

**Stop and ask the human when** authorisation is refused with credentials the human gave you, or a call rejects with a code that is not about the request.

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## Reference
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md)
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md)
- [Build: the Library of SDKs and documents](https://platformdocs.coinme.com/pages/build/library.md)
