# CaaS API clients: Coinme App Platform > Every page and skill for the CaaS API clients, in one file: the SDK documents and guides, and the Agent Skills that integrate it. The CaaS API clients belongs to the Coinme-as-a-Service (CaaS) integration; https://platformdocs.coinme.com/agents/surfaces.md explains the two surfaces. The index of the whole site is https://platformdocs.coinme.com/llms.txt. --- --- 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. --- --- title: "Transient Auth Token" url: "https://platformdocs.coinme.com/#/docs/transient-auth-token" markdown: "https://platformdocs.coinme.com/docs/transient-auth-token.md" summary: "The Vault SDK and the Onboarding SDK submit straight from the customer's browser or app to Coinme, so card numbers and Social Security Numbers never touch your code or your servers, and the Compliance SDK's attestation store reads and records what a customer accepted the same way. Those calls need a credential, and your partner access token is far too powerful to put in a web page or an app. The Transient Auth Token is the credential they carry instead: your backend trades its partner access token for a token that can make one kind of call, for one customer, for ten minutes." surface: "caas" platform: "server" updated: "2026-11-06" --- # Transient Auth Token The Vault SDK and the Onboarding SDK submit straight from the customer's browser or app to Coinme, so card numbers and Social Security Numbers never touch your code or your servers, and the Compliance SDK's attestation store reads and records what a customer accepted the same way. Those calls need a credential, and your partner access token is far too powerful to put in a web page or an app. The Transient Auth Token is the credential they carry instead: your backend trades its partner access token for a token that can make one kind of call, for one customer, for ten minutes. > **Give the Vault SDK, the Onboarding SDK and the Compliance SDK a Transient Auth Token, never your partner access token.** > > The Risk SDK takes neither: its session-tag call needs no token, so never pass it one. > **After onboarding, every call uses a token for that customer.** > > The Onboarding SDK's phone verification (sending the code, checking it) needs a Transient Auth Token with `scope=onboarding` minted for the `customerId` that onboarding returned. Never your partner access token, and never the sign-up session token you onboarded with. That token is the only thing that ties the two calls to the customer: the send carries only the phone number and the check only the code, so there is no challenge ID, session or cookie to pass from one to the other. See [Example: both tokens, end to end](https://platformdocs.coinme.com/docs/transient-auth-token.md#example-both-tokens-end-to-end). ## How the flow works 1. **Your backend gets a partner access token.** It exchanges its API client ID and client secret for a partner access token (`POST /services/authorize`). This token can call every CaaS endpoint on your behalf, so it never leaves your servers. 2. **Your backend mints a Transient Auth Token.** It calls `POST /services/browserAuth` with the partner access token, for the customer adding a card or, for onboarding, the customer's sign-up session. For the Onboarding SDK's phone verification, which follows onboarding, it mints another one for the customer that onboarding created. For the Compliance SDK's attestations, it mints one for the onboarded customer. 3. **Your backend hands it to the client.** Your web page or app receives it over your own authenticated channel and keeps it in memory. 4. **The SDK sends it on the request.** The Vault SDK's payment-method submit, the Onboarding SDK's onboarding submit and phone verification calls, and the Compliance SDK's attestation calls carry it as `Authorization: Bearer `. The Transient Auth Token is accepted by one kind of call only. Every other Coinme endpoint rejects it, so a leaked token cannot read balances, move funds or reach any other customer. ## Before you start - **API client credentials.** The client ID and client secret Coinme issued for API access. This client ID is not your partner ID, and it is not the Risk SDK's `clientId`. Keep both in your backend's secret store. - **The base URL.** Sandbox is `https://caas-staging.coinme.com`; the examples below use it. Your Coinme integration contact provides the production base URL at onboarding. - **For card capture:** the Coinme `customerId` of the signed-in customer adding the card, and the [Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) in the page or app, since the payment-method submit also carries its `webSessionId` and device fingerprint. - **For onboarding:** an identifier for the customer's sign-up session in your app. The customer does not exist at Coinme until the onboarding submit succeeds, so the token is minted for that session instead. - **For phone verification after onboarding:** the Coinme `customerId` the onboarding submit returned. The sign-up session's token does not work for these calls. - **For attestations:** the Coinme `customerId` of the onboarded customer whose consents and disclosures you read or record. ## Step 1: Get a partner access token Call this from your backend only. It authenticates with HTTP Basic: your API client ID and client secret, joined by a colon and base64-encoded. ```bash curl -X POST "https://caas-staging.coinme.com/services/authorize" \ -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" ``` ```json { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": "1800" } ``` The lifetime differs by environment: 30 minutes (`1800`) in sandbox and 60 minutes (`3600`) in production. Read `expires_in` (seconds, sent as a string) rather than hard-coding it, keep the token in your backend and reuse it until shortly before it expires. > **Never send the partner access token to a browser or an app.** > > It authorizes every CaaS endpoint on your behalf. Only the Transient Auth Token from the next step goes to the client. ## Step 2: Mint a Transient Auth Token Also from your backend only, authenticated with the partner access token from step 1. ```bash curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}" \ -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}" ``` | Parameter | In | Required | Notes | | --- | --- | --- | --- | | `Authorization` | header | yes | `Bearer `. | | `customerId` | query | yes | For card capture, the Coinme customer the card will belong to. For onboarding, your identifier for the customer's sign-up session. For phone verification, the Coinme `customerId` onboarding returned, read from your backend's own record, never from the client. For attestations, the Coinme `customerId` of the onboarded customer. The token is bound to this value. | | `scope` | query | no | `payment-methods` (the default) for the Vault SDK's payment-method submit, `onboarding` for the Onboarding SDK's onboarding submit and phone verification calls (sandbox only for now: Coinme's production environment does not issue tokens with this scope yet), or `attestations` for the Compliance SDK's attestation store, which is not available in the beta at this time. | For onboarding, pass `scope=onboarding` and the sign-up session's identifier: ```bash curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${SIGNUP_SESSION_ID}&scope=onboarding" \ -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}" ``` For phone verification, pass `scope=onboarding` and the `customerId` onboarding returned. Mint a fresh one for each verification call (sending the code, checking it), since a customer waiting for the text can easily pass the 10 minutes: ```bash curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=onboarding" \ -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}" ``` For the Compliance SDK's attestations, pass `scope=attestations` and the onboarded customer's `customerId`. Attestations are not available in the Compliance SDK beta at this time, and Coinme does not issue tokens with this scope: ```bash curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=attestations" \ -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}" ``` ```json { "access_token": "eyJ…", "token_type": "Bearer", "expires_in": "600" } ``` Mint a fresh token each time the customer reaches the add-card, onboarding or consent screen. Tokens last 10 minutes and are cheap to mint; never cache one or reuse it across sessions or customers. > **Check the body, not just the status.** > > A mint that reaches the service but fails validation returns HTTP `200` with an error envelope in the body (for example `{"status":400}`) and no `access_token`. Treat any response without an `access_token` as a failure. ### In your backend The two calls as a Node.js module. The route that hands the token to your page or app calls `mintTransientAuthToken`: for card capture, for a signed-in customer only; for onboarding, for the customer's sign-up session, because the customer is not signed in yet; for phone verification, for the `customerId` your backend saved against that customer's record when onboarding succeeded, read from your own record and never from the request; for attestations, for the signed-in customer only. ```typescript const BASE_URL = process.env.COINME_BASE_URL!; // https://caas-staging.coinme.com in sandbox let partnerToken: { value: string; expiresAt: number } | undefined; const getPartnerAccessToken = async (): Promise => { if (partnerToken && partnerToken.expiresAt > Date.now() + 60_000) { return partnerToken.value; } const credentials = Buffer.from( `${process.env.COINME_CLIENT_ID}:${process.env.COINME_CLIENT_SECRET}` ).toString('base64'); const response = await fetch(`${BASE_URL}/services/authorize`, { method: 'POST', headers: { Authorization: `Basic ${credentials}` }, }); const body = await response.json(); if (!response.ok || !body.access_token) { throw new Error(`Coinme authorize failed (${response.status})`); } partnerToken = { value: body.access_token, expiresAt: Date.now() + Number(body.expires_in) * 1000, }; return partnerToken.value; }; export const mintTransientAuthToken = async ( customerId: string, // or, for onboarding, the sign-up session's identifier scope: 'payment-methods' | 'onboarding' | 'attestations' = 'payment-methods' ): Promise<{ token: string; expiresIn: number }> => { const url = new URL(`${BASE_URL}/services/browserAuth`); url.searchParams.set('customerId', customerId); url.searchParams.set('scope', scope); const response = await fetch(url, { method: 'POST', headers: { Authorization: `Bearer ${await getPartnerAccessToken()}` }, }); const body = await response.json(); // A failed mint can arrive as HTTP 200 with an error envelope and no token. if (!response.ok || !body.access_token) { throw new Error(`Coinme browserAuth failed (${body.status ?? response.status})`); } return { token: body.access_token, expiresIn: Number(body.expires_in) }; }; ``` ## Step 3: Hand the token to the client Deliver the Transient Auth Token to your web page or app over your own authenticated channel, typically the response of the route that serves your add-card, onboarding or consent screen, or a route the client calls just before submitting. Treat it like a session credential: - Send it only to the signed-in customer, or the sign-up session, it was minted for. - Keep it in memory. Don't write it to `localStorage`, `sessionStorage`, cookies, device storage or logs. - If the customer takes longer than 10 minutes, fetch a fresh token from your backend before submitting. Each SDK takes it where it builds the submit's headers: | SDK | Where the token goes | | --- | --- | | Vault SDK | `Authorization: Bearer ` in the `headers` of the payment-method submit; see [Submitting a payment method](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#submitting-a-payment-method) and each platform's guide. | | Onboarding SDK | `{ Authorization: 'Bearer ' }` returned from `getHeaders`: the form's or provider's for the onboarding submit, the phone verification step's or hook's for the verification calls; see [Authentication and headers](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#authentication-and-headers). | | Compliance SDK | `{ Authorization: 'Bearer ' }` returned from the attestation store's `getHeaders`; see [Attestations](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#attestations). Not available in the beta at this time. | ## Example: both tokens, end to end > **This is one way to do it, not the only way.** > > It shows one way to wire the two Onboarding SDK tokens through a backend. The route names, paths, how your app signs the customer in, the framework and the storage are yours to choose. Only the Coinme API calls and the SDK's props are fixed. It does follow what Coinme recommends: > > - your backend reads the `customerId` from its own record, never from the page or app; > - your partner access token is minted and cached on your server only; > - each `getHeaders` call fetches a fresh token, kept in memory only and never stored or logged; > - the phone number is the one from the onboarding result. Who provides what: | | What | Where it runs | | --- | --- | --- | | **Coinme provides** | `POST https://caas-staging.coinme.com/services/authorize`: your partner access token (Coinme API) | Called from your backend only | | **Coinme provides** | `POST https://caas-staging.coinme.com/services/browserAuth`: a Transient Auth Token (Coinme API) | Called from your backend only | | **Coinme provides** | `CustomerOnboardingForm`, `PhoneVerificationStep` and their props (the Onboarding SDK) | Your page or app | | **You build** | `POST /your-api/onboarding/token`, `/your-api/onboarding/complete`, `/your-api/phone-verification/token` and `/your-api/phone-verification/verified` | Your backend. These are examples: Coinme doesn't provide them, so name and shape them however you like. | In production, use the base URL your Coinme integration contact gives you in place of `https://caas-staging.coinme.com`. ### You build These routes run on **your** backend. Coinme doesn't provide them: the paths are examples, so name them however you like. Only the Coinme API calls they make are fixed. | Your route (example path) | What it does | | --- | --- | | `POST /your-api/onboarding/token` | Mints a Transient Auth Token for the sign-up session: calls Coinme's `POST /services/browserAuth` with `scope=onboarding` and your own ID for the session as `customerId`. Returns `{ token }`. | | `POST /your-api/onboarding/complete` | Saves the `customerId` and `phoneNumber` from the onboarding result on the signed-in user, in your own database. | | `POST /your-api/phone-verification/token` | Looks up the signed-in user, reads the `customerId` you saved for them when onboarding succeeded, and mints a Transient Auth Token for **that** `customerId` (`scope=onboarding`). Returns `{ token }`. It never takes a `customerId` from the page or app. | | `POST /your-api/phone-verification/verified` | Records on the signed-in user that their phone is verified. | Your partner access token (from Coinme's `POST /services/authorize`) is what these routes use to call `browserAuth`. It stays on your backend and never reaches the page or app. **This is how customer IDs can't get mixed up.** Each of your users has one saved `customerId`, and the verification token route only ever mints for that one. The page or app never says which customer it is, so it can't ask for the wrong one. **Your backend** (YOUR code, shown with Express; the routes are examples; `mintTransientAuthToken` is the module from [In your backend](https://platformdocs.coinme.com/docs/transient-auth-token.md#in-your-backend)): ```typescript import express from 'express'; // Your own code: `requireSession` checks YOUR app's sign-in for the person using it, and `users` is YOUR user store. import { requireSession, users } from './your-app'; import { mintTransientAuthToken } from './coinme-tokens'; const app = express(); app.use(express.json()); // Token 1: for the sign-up session. The customer doesn't exist at Coinme yet. app.post('/your-api/onboarding/token', requireSession, async (req, res) => { const { token } = await mintTransientAuthToken(req.session.id, 'onboarding'); res.json({ token }); }); // Save what onboarding returned against YOUR user, so later tokens come from your record. app.post('/your-api/onboarding/complete', requireSession, async (req, res) => { const { customerId, phoneNumber } = req.body; await users.update(req.session.userId, { coinmeCustomerId: customerId, onboardedPhone: phoneNumber, phoneVerified: false, }); res.sendStatus(204); }); // Token 2: for this customer. The page or app never says which customer: the ID comes from // your record, so a client can only get a token for its own customer. app.post('/your-api/phone-verification/token', requireSession, async (req, res) => { const user = await users.get(req.session.userId); if (!user?.coinmeCustomerId) return res.sendStatus(409); const { token } = await mintTransientAuthToken(user.coinmeCustomerId, 'onboarding'); res.json({ token }); }); // The client reports that the code checked out. Coinme checked the code itself. app.post('/your-api/phone-verification/verified', requireSession, async (req, res) => { await users.update(req.session.userId, { phoneVerified: true }); res.sendStatus(204); }); ``` **Your page or app** (the SDK's `getHeaders` and `onSuccess` props; the React Native SDK takes the same props): ```tsx // YOUR code, not part of the SDK. These two helpers call routes on YOUR backend (see "You build" // above). The paths are examples. Keep the tokens in memory only: never store or log them. const getTokenFromYourBackend = async (path: string): Promise => { const response = await fetch(path, { method: 'POST', credentials: 'include' }); if (!response.ok) throw new Error(`Token request failed (${response.status})`); const { token } = await response.json(); return token; }; const postToYourBackend = async (path: string, body: unknown): Promise => { const response = await fetch(path, { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`Request to ${path} failed (${response.status})`); }; ({ Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/onboarding/token')}`, })} // YOUR backend route. Save the result before moving on: token 2 is minted from it. onSuccess={(result) => { void postToYourBackend('/your-api/onboarding/complete', result).then(() => setOnboarded(result)); }} />; ({ Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/phone-verification/token')}`, })} // YOUR backend route: records that this user's phone is verified. onVerified={() => void postToYourBackend('/your-api/phone-verification/verified', {})} />; ``` `setOnboarded` is your own state (for example `useState`) that switches the screen from the form to the step. For a complete way to link the `customerId` to your sign-up session, see [Example: linking onboarding to your backend session](https://platformdocs.coinme.com/docs/onboarding-sdk-session-example.md). Don't treat the customer as onboarded until the phone is verified, and send a returning customer whose phone isn't verified back to verification with the number you saved. A real integration also handles a failed request (show a retry). ### Questions about the two tokens **How do I make sure I don't mix up customer IDs? How does my backend know which customer to mint the verification token for?** From its own records, never from the page or app. When onboarding succeeds, the client sends the result to your backend, which saves the `customerId` on the signed-in user. When the client later asks for the verification token, your backend looks up the signed-in user and mints the token for the `customerId` it saved. Each user has one saved `customerId`, so the client can't ask for someone else's. **Do I pass the `customerId` to the send or check calls?** No. Neither takes one. The token carries the customer, which is why it has to be minted for that `customerId`. **Can I use my partner access token for phone verification?** No. It isn't tied to any customer, and it must never reach the browser or app. Use it only on your backend, to mint Transient Auth Tokens. **Can I reuse the onboarding token?** No. It was minted for the sign-up session, before the customer existed at Coinme. Mint a new one for the `customerId` that onboarding returned. ## What the token allows - **One kind of call.** A `payment-methods` token is accepted only by the payment-method submit (`POST /services/paymentmethods`); an `onboarding` token only by the Onboarding SDK's onboarding submit and phone verification calls; an `attestations` token only by the Compliance SDK's attestation calls. Any other endpoint, method or path is denied. - **Ten minutes.** It cannot be refreshed; mint a new one instead. - **One customer.** It is bound to the `customerId` it was minted for, and a submit for anyone else fails. For phone verification this binding is the only link between the calls and the customer: neither the send nor the check carries a customer ID, challenge ID, session or cookie, so the token you authorize them with decides which customer they act on. - **Opaque.** It is a signed token, but read nothing from it and build nothing on its contents; they can change. ## Errors and troubleshooting ### Minting | Response | Cause | Fix | | --- | --- | --- | | `200` with body `{"status":400}` | Missing or blank `customerId`. The HTTP status is `200`; the error is in the body. | Send `customerId`, and check the body for `access_token`, not just the HTTP status. | | `401` `{"message":"Unauthorized"}` | The partner access token is missing, malformed, expired or invalid, or the `Authorization` header is not a Bearer token. | Get a new partner access token (step 1) and retry with `Authorization: Bearer `. | | `5xx` | A transient service error. | Retry with backoff; if it persists, ask your Coinme integration contact. | ### Submitting The token most often fails because it expired: customers routinely take longer than 10 minutes to type a card or their details on a phone. Mint when the screen opens, and when a submit fails as unauthorized, fetch a fresh token from your backend and retry the submit once before showing an error. | SDK | What an expired or rejected token looks like | | --- | --- | | Vault SDK | A `CoinmeVaultError` of kind `server` with `status` `401` or `403`. | | Onboarding SDK | A `CoinmeOnboardingError` of kind `unauthorized`. Phone verification returns it too for a partner access token or the sign-up session token, which are rejected there: mint a fresh token for the onboarded `customerId`. | | Compliance SDK | A `CoinmeComplianceError` of kind `unauthorized`. | ## Security rules - **The partner access token stays on your servers.** Only the Transient Auth Token reaches the client. - **Mint per customer and per session.** Never share a Transient Auth Token between customers, or persist one. - **Never log tokens** of either kind, in the client or on the server. - **Keep the client secret in your backend's secret store,** out of source control and out of anything you ship. - **Let the SDK handle sensitive data.** Card numbers and Social Security Numbers go from the secure fields to Coinme; never put them in `headers` or your own request data. --- --- 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 ``` Returns `Promise`. ```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 ``` | 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 ``` | 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 \| 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 = { [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[]` | 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; } ``` --- --- title: "Prove onboarding API client" url: "https://platformdocs.coinme.com/#/docs/caas-prove-onboarding-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md" summary: "The `@coinme/prove-onboarding-api-client` package provides a client for interacting with the Coinme Prove Onboarding APIs." surface: "caas" platform: "server" package: "@coinme/prove-onboarding-api-client" updated: "2026-11-04" --- # Prove onboarding API client The `@coinme/prove-onboarding-api-client` package provides a client for interacting with the Coinme Prove Onboarding APIs. > **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/prove-onboarding-api-client@^2.0.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 interacting with the Prove Onboarding APIs. ```typescript import { APIClient } from '@coinme/prove-onboarding-api-client'; const onboardingClient = new APIClient({ baseUrl: 'https://caas-staging.coinme.com/services', onboardingBaseUrl: process.env.COINME_ONBOARDING_BASE_URL!, 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. | | `onboardingBaseUrl` | `string` | Yes | Base URL of the secure onboarding host for the environment to call, including the `/services` path. Customer onboarding, which carries the customer's KYC data, is sent here; every other call uses `baseUrl`. | | `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 ### createInstantLink Initiate authentication flow with an instant link. This flow will result in an SMS containing the redirect URL being sent to the provided mobile phone number. ```typescript createInstantLink(body: CreateInstantLinkRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateInstantLinkRequest` | The parameters required to create an instant link. | A promise that resolves to a `CreateInstantLinkResponse`. See [CreateInstantLinkResponse](#createinstantlinkresponse), [CreateInstantLinkRequest](#createinstantlinkrequest). ```typescript const response = await onboardingClient.createInstantLink({ mobileNumber: 'mobile-number', }); ``` ### customerOnboarding Initiates the customer onboarding process. ```typescript customerOnboarding(body: CustomerOnboardingRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CustomerOnboardingRequest` | The parameters required to initiate the customer onboarding process. | A promise that resolves to a `CustomerOnboardingResponse`. See [CustomerOnboardingResponse](#customeronboardingresponse), [CustomerOnboardingRequest](#customeronboardingrequest). ```typescript const response = await onboardingClient.customerOnboarding({ address: { city: 'city', country: 'US', line1: 'line1', postalCode: '98101', state: 'WA', }, dateOfBirth: '1990-01-01', email: 'customer@example.com', fullName: { firstName: 'first-name', lastName: 'last-name', }, phoneNumber: { countryCode: 'US', number: 'number', }, SSN: 'ssn', }); ``` ### finalizeInstantLink Finalize instant link authentication process. ```typescript finalizeInstantLink(body: FinalizeMobileAuthRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `FinalizeMobileAuthRequest` | The parameters required to finalize the instant link authentication process. | A promise that resolves to a `FinalizeInstantLinkResponse`. See [FinalizeInstantLinkResponse](#finalizeinstantlinkresponse), [FinalizeMobileAuthRequest](#finalizemobileauthrequest). ```typescript const response = await onboardingClient.finalizeInstantLink({ verificationFingerprint: 'verification-fingerprint', }); ``` ### finalizeMobileAuth Finalize mobile auth. ```typescript finalizeMobileAuth(body: FinalizeMobileAuthRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `FinalizeMobileAuthRequest` | The parameters required to finalize mobile auth. | A promise that resolves to a `FinalizeMobileAuthResponse`. See [FinalizeMobileAuthResponse](#finalizemobileauthresponse), [FinalizeMobileAuthRequest](#finalizemobileauthrequest). ```typescript const response = await onboardingClient.finalizeMobileAuth({ verificationFingerprint: 'verification-fingerprint', }); ``` ### getInstantLinkById Get instant link by ID. ```typescript getInstantLinkById(authId: string): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `authId` | `string` | The unique identifier appended to the `smsRedirectUrl` from the initiate link response. | A promise that resolves to a `GetInstantLinkByIdResponse`. See [GetInstantLinkByIdResponse](#getinstantlinkbyidresponse). ```typescript const response = await onboardingClient.getInstantLinkById('auth-id'); ``` ### initiateMobileAuth Initiate mobile auth. ```typescript initiateMobileAuth(body: InitiateMobileAuthRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `InitiateMobileAuthRequest` | The parameters required to initiate mobile auth. | A promise that resolves to a `InitiateMobileAuthResponse`. See [InitiateMobileAuthResponse](#initiatemobileauthresponse), [InitiateMobileAuthRequest](#initiatemobileauthrequest). ```typescript const response = await onboardingClient.initiateMobileAuth({ consentCollectedTimestamp: 'consent-collected-timestamp', consentDescription: 'consent-description', consentTransactionId: 'consent-transaction-id', }); ``` ### retrieveIdentityInformation Looks up the identity details registered to a phone number, to pre-fill onboarding. Send the phone number with the last four digits of the customer's Social Security Number (`last4`) or their date of birth (`dob`). The SSN in the response is a token issued through the vault provider, never the number itself. ```typescript retrieveIdentityInformation(body: RetrieveIdentityInformationRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `RetrieveIdentityInformationRequest` | The parameters required to retrieve identity information. | A promise that resolves to a `RetrieveIdentityInformationResponse`. See [RetrieveIdentityInformationResponse](#retrieveidentityinformationresponse), [RetrieveIdentityInformationRequest](#retrieveidentityinformationrequest). ```typescript const response = await onboardingClient.retrieveIdentityInformation({ last4: '1234', phoneNumber: 'phone-number', }); ``` ### 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 onboardingClient.updateToken('new-token'); ``` ### verifyIdentity Verify user identity. ```typescript verifyIdentity(body: VerifyIdentityRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `VerifyIdentityRequest` | The parameters required to verify the user's identity. | A promise that resolves to a `VerifyIdentityResponse`. See [VerifyIdentityResponse](#verifyidentityresponse), [VerifyIdentityRequest](#verifyidentityrequest). ```typescript const response = await onboardingClient.verifyIdentity({ phoneNumber: 'phone-number', }); ``` ## 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. ### CreateInstantLinkRequest Request for `POST /services/sendAuthSms`: Initiate Instant Link. | Property | Type | Required | Description | | --- | --- | --- | --- | | `deviceIp` | `string` | No | IP of mobile device. Can be IPv4 or IPv6 | | `mobileNumber` | `string` | Yes | Phone number to send link to | | `requestId` | `string` | No | Optional requestId that can be used to track the requests through the entire Instant Link flow. If not sent, it will be generated automatically | | `sessionId` | `string` | No | | ### CreateInstantLinkResponse Response for `POST /services/sendAuthSms`: Initiate Instant Link. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authUrl` | `string \| null` | No | | | `requestId` | `string \| null` | No | | ### CustomerOnboardingRequest Request for `POST /services/customeronboarding`: Initiate Customer Onboarding. | Property | Type | Required | Description | | --- | --- | --- | --- | | `address` | `object` | Yes | Full home address of customer | | `address.city` | `string` | Yes | City of customer home address | | `address.country` | `string` | Yes | 3 character abbreviation of country of customer's home address (i.e. USA) | | `address.line1` | `string` | Yes | Line 1 of customer home address | | `address.line2` | `string` | No | Line 2 of customer home address | | `address.postalCode` | `string` | Yes | Postal code of customer home address | | `address.state` | `string` | Yes | State of customer home address | | `dateOfBirth` | `string` | Yes | Date of birth in format YYYY-MM-DD | | `email` | `string` | Yes | Email of customer Format: email. | | `fullName` | `object` | Yes | Full legal name of customer | | `fullName.firstName` | `string` | Yes | First name of customer | | `fullName.lastName` | `string` | Yes | Last name of customer | | `fullName.middleName` | `string` | No | Middle name of customer | | `fullName.otherNames` | `string[]` | No | | | `phoneNumber` | `object` | Yes | 10-digit phone number | | `phoneNumber.countryCode` | `string` | Yes | Country code of phone number (i.e. 1) | | `phoneNumber.number` | `string` | Yes | 10-digit phone number | | `SSN` | `string` | Yes | Social security number of the customer | ### CustomerOnboardingResponse Response for `POST /services/customeronboarding`: Initiate Customer Onboarding. | Property | Type | Required | Description | | --- | --- | --- | --- | | `customerId` | `string \| null` | No | | | `status` | `string \| null` | No | | ### FinalizeInstantLinkRequest Request for `POST /services/authLinkResult`: Initiate Instant Link Finish. | Property | Type | Required | Description | | --- | --- | --- | --- | | `requestId` | `string` | No | | | `verificationFingerprint` | `string` | Yes | Extracted from the URL at finalTargetUrl | ### FinalizeInstantLinkResponse Response for `POST /services/authLinkResult`: Initiate Instant Link Finish. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authenticatedPhoneNumber` | `string \| null` | No | | | `requestId` | `string \| null` | No | | ### FinalizeMobileAuthRequest Request for `POST /services/mobileAuthFinish`: Finish Mobile Auth. | Property | Type | Required | Description | | --- | --- | --- | --- | | `requestId` | `string` | No | | | `verificationFingerprint` | `string` | Yes | Extracted from the URL at finalTargetUrl | ### FinalizeMobileAuthResponse Response for `POST /services/mobileAuthFinish`: Finish Mobile Auth. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authenticatedPhoneNumber` | `string \| null` | No | | | `requestId` | `string \| null` | No | | ### GetInstantLinkByIdPathParams PathParams for `GET /services/smsAuth/{authId}`: Get Instant Link by ID. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authId` | `string` | Yes | authId appended to the smsRedirectUrl from the Initiate Instant Link response | ### GetInstantLinkByIdResponse Where an instant link sends the customer. The API answers the link with a redirect to the authentication page rather than with a JSON body. | Property | Type | Required | Description | | --- | --- | --- | --- | | `redirectUrl` | `string` | Yes | The authentication URL the instant link redirects to. | ### InitiateMobileAuthRequest Request for `POST /services/mobileAuth`: Initiate Mobile Auth. | Property | Type | Required | Description | | --- | --- | --- | --- | | `consentCollectedTimestamp` | `string` | Yes | Date/Time field when the original consent was collected by the client (format: YYYY-MM-DD) Format: date. | | `consentDescription` | `string` | Yes | The client describes the type of consent (electronic/paper), use case and reference to the version of Terms and Conditions (T&Cs), if applicable | | `consentStatus` | `'optedIn' \| 'optedOut' \| 'notCollected' \| 'unknown'` | No | | | `consentTransactionId` | `string` | Yes | Unique id of the consent collected by the client | | `deviceIp` | `string` | No | IP of mobile device. Can be IPv4 or IPv6 | | `requestId` | `string` | No | Optional requestId that can be used to track the requests through the entire Mobile Auth flow. If not sent, it will be generated automatically | ### InitiateMobileAuthResponse Response for `POST /services/mobileAuth`: Initiate Mobile Auth. | Property | Type | Required | Description | | --- | --- | --- | --- | | `redirectTargetUrl` | `string \| null` | No | | | `requestId` | `string \| null` | No | | ### RetrieveIdentityInformationRequest Request for `POST /services/identity`: Initiate Identity Pre-Fill. | Property | Type | Required | Description | | --- | --- | --- | --- | | `consentStatus` | `'optedIn' \| 'optedOut' \| 'notCollected' \| 'unknown'` | No | | | `dob` | `string` | No | | | `last4` | `string` | No | Last 4 digits of the Social Security Number (SSN) | | `phoneNumber` | `string` | Yes | 10-digit phone number | | `requestId` | `string` | No | | ### RetrieveIdentityInformationResponse Response for `POST /services/identity`: Initiate Identity Pre-Fill. | Property | Type | Required | Description | | --- | --- | --- | --- | | `additionalInfo` | `string \| null` | No | | | `description` | `string \| null` | No | | | `requestId` | `string \| null` | No | | | `response` | `object \| null` | No | | | `response.carrier` | `string \| null` | No | | | `response.countryCode` | `string \| null` | No | | | `response.individual` | `object \| null` | No | | | `response.individual.addresses` | `object[] \| null` | No | | | `response.individual.addresses[].address` | `string \| null` | No | | | `response.individual.addresses[].city` | `string \| null` | No | | | `response.individual.addresses[].extendedAddress` | `string \| null` | No | | | `response.individual.addresses[].postalCode` | `string \| null` | No | | | `response.individual.addresses[].region` | `string \| null` | No | | | `response.individual.dob` | `string \| null` | No | | | `response.individual.emailAddresses` | `string[] \| null` | No | | | `response.individual.firstName` | `string \| null` | No | | | `response.individual.lastName` | `string \| null` | No | | | `response.individual.ssn` | `string \| null` | No | An SSN token issued through the vault provider, not the number itself. | | `response.lineType` | `string \| null` | No | | | `response.phoneNumber` | `string \| null` | No | | | `response.reasonCodes` | `string[] \| null` | No | | | `response.transactionId` | `string \| null` | No | | | `status` | `number \| null` | No | | ### VerifyIdentityRequest Request for `POST /services/verify`: Initiate Verify. | Property | Type | Required | Description | | --- | --- | --- | --- | | `address` | `string` | No | Line 1 of customer home address | | `city` | `string` | No | City of customer home address | | `consentStatus` | `string` | No | enum of optedIn, optedOut, notCollected, unknown | | `dob` | `string` | No | Date of birth of customer in format YYYY-MM-DD | | `driversLicenseNumber` | `string` | No | | | `driversLicenseState` | `string` | No | | | `emailAddress` | `string` | No | | | `extendedAddress` | `string` | No | Line 2 of customer home address | | `firstName` | `string` | No | First name of customer | | `last4` | `string` | No | | | `lastName` | `string` | No | Last name of customer | | `phoneNumber` | `string` | Yes | 10-digit phone number | | `postalCode` | `string` | No | Postal code of customer home address | | `region` | `string` | No | State of customer home address | | `requestId` | `string` | No | | ### VerifyIdentityResponse Response for `POST /services/verify`: Initiate Verify. | Property | Type | Required | Description | | --- | --- | --- | --- | | `additionalInfo` | `string \| null` | No | | | `description` | `string \| null` | No | | | `requestId` | `string \| null` | No | | | `response` | `object \| null` | No | | | `response.address` | `object \| null` | No | | | `response.address.addressScore` | `number \| null` | No | | | `response.address.city` | `boolean \| null` | No | | | `response.address.distance` | `number \| null` | No | | | `response.address.postalCode` | `boolean \| null` | No | | | `response.address.region` | `boolean \| null` | No | | | `response.address.street` | `boolean \| null` | No | | | `response.address.streetNumber` | `number \| null` | No | | | `response.carrier` | `string \| null` | No | | | `response.countryCode` | `string \| null` | No | | | `response.identifiers` | `object \| null` | No | | | `response.identifiers.dob` | `boolean \| null` | No | | | `response.identifiers.driversLicenseNumber` | `boolean \| null` | No | | | `response.identifiers.driversLicenseState` | `boolean \| null` | No | | | `response.identifiers.last4` | `boolean \| null` | No | | | `response.identifiers.ssn` | `boolean \| null` | No | | | `response.knowYourCustomer` | `object \| null` | No | | | `response.knowYourCustomer.amlTypeLists` | `object[] \| null` | No | | | `response.knowYourCustomer.amlTypeLists[].amlType` | `string \| null` | No | | | `response.knowYourCustomer.amlTypeLists[].fields` | `({ name?: ... \| ... \| ...; source?: ... \| ... \| ...; value?: ... \| ... \| ... })[] \| null` | No | | | `response.knowYourCustomer.amlTypeLists[].listHits` | `number \| null` | No | | | `response.knowYourCustomer.totalHits` | `number \| null` | No | | | `response.lineType` | `string \| null` | No | | | `response.matchDataType` | `string \| null` | No | | | `response.name` | `object \| null` | No | | | `response.name.firstName` | `number \| null` | No | | | `response.name.lastName` | `number \| null` | No | | | `response.name.nameScore` | `number \| null` | No | | | `response.payfoneAlias` | `string \| null` | No | | | `response.phoneNumber` | `string \| null` | No | | | `response.reasonCodes` | `string[] \| null` | No | | | `response.transactionId` | `string \| null` | No | | | `response.verified` | `boolean \| null` | No | | | `status` | `number \| null` | No | | ### Address The customer's home address. ```typescript type Address = CustomerOnboardingRequest['address']; ``` ### AddressInfo One of the person's addresses. ```typescript type AddressInfo = NonNullable[number]; ``` ### AmlFields One matched field of an anti-money-laundering list hit. ```typescript type AmlFields = NonNullable[number]; ``` ### AmlType Hits on one anti-money-laundering list. ```typescript type AmlType = NonNullable[number]; ``` ### FullName The customer's full legal name. ```typescript type FullName = CustomerOnboardingRequest['fullName']; ``` ### Identifiers Which submitted identifiers matched. ```typescript type Identifiers = NonNullable; ``` ### IdentityInformation The identity details in a `RetrieveIdentityInformationResponse`. ```typescript type IdentityInformation = NonNullable; ``` ### IdentityVerificationResult The verification result in a `VerifyIdentityResponse`. ```typescript type IdentityVerificationResult = NonNullable; ``` ### Individual The person the phone number belongs to. ```typescript type Individual = NonNullable; ``` ### KnowYourCustomer Anti-money-laundering list results. ```typescript type KnowYourCustomer = NonNullable; ``` ### Name How well the submitted name matched. ```typescript type Name = NonNullable; ``` ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [P in keyof T]: T[P] | null }; ``` ### PhoneNumber The customer's phone number, split into country code and number. ```typescript type PhoneNumber = CustomerOnboardingRequest['phoneNumber']; ``` ### VerifiedAddress How well the submitted address matched. ```typescript type VerifiedAddress = NonNullable; ``` ### 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 | | --- | --- | | `CreateInstantLinkBodyParams` | `CreateInstantLinkRequest` | | `CustomerOnboardingBodyParams` | `CustomerOnboardingRequest` | | `InitiateMobileAuthBodyParams` | `InitiateMobileAuthRequest` | | `RetrieveIdentityInformationBodyParams` | `RetrieveIdentityInformationRequest` | | `VerificationBodyParams` | `FinalizeMobileAuthRequest` | | `VerifyIdentityBodyParams` | `VerifyIdentityRequest` | ## 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[]` | 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/prove-onboarding-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- title: "Quotes API client" url: "https://platformdocs.coinme.com/#/docs/caas-quotes-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-quotes-api-client.md" summary: "The `@coinme/quotes-api-client` package provides a client for interacting with the Coinme Quotes APIs." surface: "caas" platform: "server" package: "@coinme/quotes-api-client" updated: "2026-11-04" --- # Quotes API client The `@coinme/quotes-api-client` package provides a client for interacting with the Coinme Quotes APIs. > **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/quotes-api-client@^2.0.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 interacting with the Coinme Quotes APIs. ```typescript import { APIClient } from '@coinme/quotes-api-client'; const quotesClient = 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 ### createBuyInformationalQuote Fetch an informational crypto quote for a buy transaction. ```typescript createBuyInformationalQuote(body: CreateInformationalQuoteRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateInformationalQuoteRequest` | The request body containing details for the crypto quote. | A promise that resolves to the `CreateInformationalQuoteResponse` with the quote details. See [CreateInformationalQuoteResponse](#createinformationalquoteresponse), [CreateInformationalQuoteRequest](#createinformationalquoterequest). ```typescript const response = await quotesClient.createBuyInformationalQuote({ amountCurrencyCode: 'USD', amountValue: '100', creditCurrencyCode: 'BTC', debitCurrencyCode: 'USD', }); ``` ### createBuyTransactionalQuote Create quote for a buy transaction. ```typescript createBuyTransactionalQuote(body: CreateTransactionalQuoteRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateTransactionalQuoteRequest` | The parameters required to create a transactional quote. | A promise that resolves to a `CreateTransactionalQuoteResponse`. See [CreateTransactionalQuoteResponse](#createtransactionalquoteresponse), [CreateTransactionalQuoteRequest](#createtransactionalquoterequest). ```typescript const response = await quotesClient.createBuyTransactionalQuote({ amountCurrencyCode: 'USD', amountValue: '100', creditCurrencyCode: 'BTC', customerId: 'customer-id', debitCurrencyCode: 'USD', }); ``` ### createSellInformationalQuote Fetch an informational crypto quote for a sell transaction. ```typescript createSellInformationalQuote(body: CreateInformationalQuoteRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateInformationalQuoteRequest` | The request body containing details for the crypto quote. | A promise that resolves to the `CreateInformationalQuoteResponse` with the quote details. See [CreateInformationalQuoteResponse](#createinformationalquoteresponse), [CreateInformationalQuoteRequest](#createinformationalquoterequest). ```typescript const response = await quotesClient.createSellInformationalQuote({ amountCurrencyCode: 'BTC', amountValue: '100', creditCurrencyCode: 'USD', debitCurrencyCode: 'BTC', }); ``` ### createSellTransactionalQuote Create quote for a sell transaction. ```typescript createSellTransactionalQuote(body: CreateTransactionalQuoteRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateTransactionalQuoteRequest` | The parameters required to create a transactional quote. | A promise that resolves to a `CreateTransactionalQuoteResponse`. See [CreateTransactionalQuoteResponse](#createtransactionalquoteresponse), [CreateTransactionalQuoteRequest](#createtransactionalquoterequest). ```typescript const response = await quotesClient.createSellTransactionalQuote({ amountCurrencyCode: 'BTC', amountValue: '100', creditCurrencyCode: 'USD', customerId: 'customer-id', debitCurrencyCode: 'BTC', }); ``` ### getLimits Return the remaining limit based on varying transaction limits that are dynamically imposed on the customer, based on risk analysis and documents/data collected. ```typescript getLimits(queryParams: GetLimitsQuery): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `queryParams` | `GetLimitsQuery` | The parameters required for fetching the customer's transaction limits. | A promise that resolves to `GetLimitsResponse`. See [GetLimitsResponse](#getlimitsresponse), [GetLimitsQuery](#getlimitsquery). ```typescript const response = await quotesClient.getLimits({ customerId: 'customer-id', fiatCurrencyCode: 'USD', }); ``` ### getTransactionalQuote Get details on a transactional quote based on the `quoteId`. ```typescript getTransactionalQuote(quoteId: string): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `quoteId` | `string` | The unique identifier for the transactional quote. | A promise that resolves to a `TransactionalQuoteResponse`. See [GetTransactionalQuoteResponse](#gettransactionalquoteresponse). ```typescript const response = await quotesClient.getTransactionalQuote('quote-id'); ``` ### 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 quotesClient.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. ### CreateInformationalQuoteRequest Request for `POST /services/cryptoquote/informative`: Initiate Informative Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `amountCurrencyCode` | `string` | Yes | Currency code of amount (i.e. USD) | | `amountValue` | `string` | Yes | Amount to buy or sell | | `chain` | `string` | No | Possible values are "XLM" or "ETH". use only if Coinme supports trading this currency on multiple chains. otherwise unnecessary | | `creditCurrencyCode` | `string` | Yes | Credit currency code (i.e. DOGE) | | `cryptoSettlementType` | `'INTERNAL' \| 'EXTERNAL'` | No | Possible values are "INTERNAL" or "EXTERNAL". defaults to "INTERNAL". Use "EXTERNAL" to also calculate blockchain fees | | `debitCurrencyCode` | `string` | Yes | Debit currency code (i.e. USD) | | `latitude` | `number` | No | Latitude of the selected location. Either lat & long , or the locationReference must be provided | | `locationReference` | `string` | No | Encoded reference of the location. Either lat & long , or the locationReference must be provided | | `longitude` | `number` | No | Longitude of the selected location. Either lat & long , or the locationReference must be provided | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread'` | No | Applies promotional fees for this transaction. Please contact your Coinme Account Manager to set up a custom promotional code | | `providerId` | `string` | No | | | `rampId` | `string` | No | | ### CreateInformationalQuoteResponse Response for `POST /services/cryptoquote/informative`: Initiate Informative Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `chain` | `string \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `feeCurrency` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread' \| null` | No | | | `spread` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | ### CreateTransactionalQuoteRequest Request for `POST /services/cryptoquote`: Initiate Transactional Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `amountCurrencyCode` | `string` | Yes | Currency code of amount (i.e. USD). It must match either creditCurrency or debitCurrency | | `amountValue` | `string` | Yes | Amount to buy or sell. This is used as the input value to calculate the quote | | `chain` | `string` | No | Possible values are "XLM", "ETH", or "LINEA". Use only if Coinme supports trading this currency on multiple chains. otherwise unnecessary | | `creditCurrencyCode` | `string` | Yes | Credit currency code (i.e. DOGE) | | `cryptoSettlementType` | `'INTERNAL' \| 'EXTERNAL'` | No | Possible values are "INTERNAL" or "EXTERNAL". defaults to "INTERNAL". Use "EXTERNAL" to also calculate blockchain fees | | `customerId` | `string` | Yes | Unique customer identifier | | `debitCurrencyCode` | `string` | Yes | Debit currency code (i.e. USD) | | `isLedgerSend` | `boolean` | No | | | `latitude` | `number` | No | | | `locationReference` | `string` | No | should be specified only if fiat settlement is done through Coinme and requires a physical location (i.e. selling crypto for cash) | | `longitude` | `number` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread'` | No | Applies promotional fees for this transaction. Please contact your Coinme Account Manager to set up a custom promotional code | | `providerId` | `string` | No | ID of payment provider (provided by Coinme) | | `rampId` | `string` | No | | | `userQuoteLocation` | `object` | No | | | `userQuoteLocation.address1` | `string` | No | | | `userQuoteLocation.address2` | `string` | No | | | `userQuoteLocation.city` | `string` | No | | | `userQuoteLocation.coordinates` | `object` | No | | | `userQuoteLocation.coordinates.latitude` | `number` | Yes | | | `userQuoteLocation.coordinates.longitude` | `number` | Yes | | | `userQuoteLocation.country` | `string` | No | | | `userQuoteLocation.description` | `string` | No | | | `userQuoteLocation.locationReference` | `string` | No | | | `userQuoteLocation.state` | `string` | No | | | `userQuoteLocation.zipcode` | `string` | No | | ### CreateTransactionalQuoteResponse Response for `POST /services/cryptoquote`: Initiate Transactional Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `chain` | `string \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `expirationTime` | `string \| null` | No | Format: date-time. | | `expiresIn` | `number \| null` | No | | | `feeCurrency` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread' \| null` | No | | | `quoteId` | `string \| null` | No | | | `spread` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | ### GetLimitsQuery Query for `GET /services/transactionlimits`: Get Transaction Limits. | Property | Type | Required | Description | | --- | --- | --- | --- | | `customerId` | `string` | Yes | Unique customer identifier | | `fiatCurrencyCode` | `string` | Yes | Currency code of the fiat (i.e. USD) | ### GetLimitsResponse Response for `GET /services/transactionlimits`: Get Transaction Limits. | Property | Type | Required | Description | | --- | --- | --- | --- | | `buyLimitAmount` | `number \| null` | No | | | `sellLimitAmount` | `number \| null` | No | | ### GetTransactionalQuotePathParams PathParams for `GET /services/cryptoquote/{quoteId}`: Get Transactional Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `quoteId` | `string` | Yes | Quote Identifier referring to the specific crypto quote | ### GetTransactionalQuoteResponse Response for `GET /services/cryptoquote/{quoteId}`: Get Transactional Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `chain` | `string \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `expirationTime` | `string \| null` | No | Format: date-time. | | `expiresIn` | `number \| null` | No | | | `feeCurrency` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread' \| null` | No | | | `quoteId` | `string \| null` | No | | | `spread` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | ### BaseQuoteBodyParams The quote fields shared by transactional and informational quotes: a transactional quote request without the customer. ```typescript type BaseQuoteBodyParams = Omit; ``` ### FeesMap Fees for the quote, by fee name. ```typescript type FeesMap = NonNullable; ``` ### GPSCoordinates GPS coordinates of a cash location. ```typescript type GPSCoordinates = NonNullable['coordinates']>; ``` ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [P in keyof T]: T[P] | null }; ``` ### Quote Quote details without a quote id or expiry, as an informational quote returns them. ```typescript type Quote = CreateInformationalQuoteResponse; ``` ### 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 | | --- | --- | | `CreateInformationalQuoteBodyParams` | `CreateInformationalQuoteRequest` | | `CreateTransactionalQuoteBodyParams` | `CreateTransactionalQuoteRequest` | | `GetLimitsQueryParams` | `GetLimitsQuery` | | `InformationalQuoteResponse` | `CreateInformationalQuoteResponse` | | `TransactionalQuoteResponse` | `GetTransactionalQuoteResponse` | ## 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[]` | 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/quotes-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- title: "Transactions API client" url: "https://platformdocs.coinme.com/#/docs/caas-transactions-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-transactions-api-client.md" summary: "The `@coinme/transactions-api-client` package provides a client for interacting with the Coinme Transactions APIs." surface: "caas" platform: "server" package: "@coinme/transactions-api-client" updated: "2026-11-04" --- # Transactions API client The `@coinme/transactions-api-client` package provides a client for interacting with the Coinme Transactions APIs. > **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/transactions-api-client@^2.0.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 interacting with the Coinme Transactions APIs. ```typescript import { APIClient } from '@coinme/transactions-api-client'; const transactionsClient = 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 ### buy Initiates a buy transaction. ```typescript buy(body: CreateQuoteAndTransactionRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateQuoteAndTransactionRequest` | The request body containing the parameters needed for a buy transaction. | A promise that resolves to the `TransactionResponse` with the transaction details. See [CreateTransactionResponse](#createtransactionresponse), [CreateQuoteAndTransactionRequest](#createquoteandtransactionrequest). ```typescript const response = await transactionsClient.buy({ customerId: 'customer-id', quoteInput: { amountCurrencyCode: 'USD', creditCurrencyCode: 'BTC', debitCurrencyCode: 'USD', providerId: 'provider-id', }, }); ``` ### buyWithQuote Initiates a buy transaction with existing quote. ```typescript buyWithQuote(body: CreateTransactionRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateTransactionRequest` | The request body containing the parameters needed for a buy transaction. | A promise that resolves to the `TransactionResponse` with the transaction details. See [CreateTransactionResponse](#createtransactionresponse), [CreateTransactionRequest](#createtransactionrequest). ```typescript const response = await transactionsClient.buyWithQuote({ customerId: 'customer-id', quoteId: 'quote-id', }); ``` ### sell Initiates a sell transaction. ```typescript sell(body: CreateQuoteAndTransactionRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateQuoteAndTransactionRequest` | The request body containing the parameters needed for a sell transaction. | A promise that resolves to the `TransactionResponse` with the transaction details. See [CreateTransactionResponse](#createtransactionresponse), [CreateQuoteAndTransactionRequest](#createquoteandtransactionrequest). ```typescript const response = await transactionsClient.sell({ customerId: 'customer-id', quoteInput: { amountCurrencyCode: 'BTC', creditCurrencyCode: 'USD', debitCurrencyCode: 'BTC', providerId: 'provider-id', }, }); ``` ### sellAll Sell all of the customer's remaining cryptocurrency as specified. This is usable only if the user’s crypto assets are managed by Coinme’s custody wallet. ```typescript sellAll(body: SellAllRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `SellAllRequest` | The request body containing details needed to sell customer's cryptocurrency. | A promise that resolves to the `SellAllResponse` with the transaction details. See [SellAllResponse](#sellallresponse), [SellAllRequest](#sellallrequest). ```typescript const response = await transactionsClient.sellAll({ creditCurrencyCode: 'USD', customerId: 'customer-id', debitCurrencyCode: 'BTC', }); ``` ### sellWithQuote Initiates a sell transaction with existing quote. ```typescript sellWithQuote(body: CreateTransactionRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateTransactionRequest` | The request body containing the parameters needed for a sell transaction. | A promise that resolves to the `TransactionResponse` with the transaction details. See [CreateTransactionResponse](#createtransactionresponse), [CreateTransactionRequest](#createtransactionrequest). ```typescript const response = await transactionsClient.sellWithQuote({ customerId: 'customer-id', quoteId: 'quote-id', }); ``` ### submitBlockchainId Submits the on-chain transaction hash of a sell order whose crypto the partner sends to Coinme from an external wallet. ```typescript submitBlockchainId(body: SubmitBlockchainIdRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `SubmitBlockchainIdRequest` | The sell transaction, its blockchain transaction id and an optional refund address. | A promise that resolves to the `SubmitBlockchainIdResponse`. See [SubmitBlockchainIdResponse](#submitblockchainidresponse), [SubmitBlockchainIdRequest](#submitblockchainidrequest). ```typescript const response = await transactionsClient.submitBlockchainId({ blockchainTransactionId: 'blockchain-transaction-id', partnerTransactionId: 'partner-transaction-id', }); ``` ### 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 transactionsClient.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. ### CreateQuoteAndTransactionRequest Request for `POST /services/quote-and-transaction`: Initiate Buy or Sell without Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `bankPaymentRail` | `'ACH_STANDARD' \| 'ACH_SAMEDAY' \| 'RTP' \| 'DOMESTIC_FED_WIRE'` | No | | | `bankTransferBeneficiaryId` | `string` | No | | | `bankTransferDetails` | `object` | No | | | `bankTransferDetails.achAddenda` | `string` | No | | | `bankTransferDetails.rtpRemittanceData` | `string` | No | | | `bankTransferDetails.wireOriginatorToBeneficiary` | `string` | No | | | `customerId` | `string` | Yes | Unique customer identifier | | `externalCustodyCreditInfo` | `object` | No | Applicable for BUY flow only when sending to an external wallet (not custodied by Coinme), details for sending crypto to external wallet | | `externalCustodyCreditInfo.blockchainMemo` | `string` | No | Blockchain memo for transaction (if applicable) | | `externalCustodyCreditInfo.walletAddress` | `string` | Yes | Wallet address to send crypto to. Required for external crypto deposit | | `externalSessionId` | `string` | No | | | `originatorNumOwner` | `'COINME' \| 'PARTNER' \| 'USER'` | No | | | `partnerTransactionId` | `string` | No | Optional - automatically generated if not provided | | `paymentMethodId` | `string` | No | Optional - required if using Coinme digital payment processing | | `quoteInput` | `object` | Yes | Details required to create a quote | | `quoteInput.amountCurrencyCode` | `string` | Yes | Currency code of amount (i.e. USD) | | `quoteInput.amountValue` | `string` | No | Amount to buy or sell | | `quoteInput.chain` | `string` | No | Possible values are "XLM", "ETH", or "LINEA". Use only if Coinme supports trading this currency on multiple chains. otherwise unnecessary | | `quoteInput.creditCurrencyCode` | `string` | Yes | Credit currency code (i.e. DOGE) | | `quoteInput.cryptoSettlementType` | `'INTERNAL' \| 'EXTERNAL'` | No | Possible values are "INTERNAL" or "EXTERNAL". defaults to "INTERNAL". Use "EXTERNAL" to also calculate blockchain fees | | `quoteInput.debitCurrencyCode` | `string` | Yes | Debit currency code (i.e. USD) | | `quoteInput.gpsCoordinates` | `object` | No | alternative to locationReference | | `quoteInput.gpsCoordinates.latitude` | `number` | No | latitude of location when selling crypto for cash (i.e. -78.617716) | | `quoteInput.gpsCoordinates.longitude` | `number` | No | longitude of location when selling crypto for cash (i.e. 62.936942) | | `quoteInput.isLedgerSend` | `boolean` | No | | | `quoteInput.locationReference` | `string` | No | should be specified only if fiat settlement is done through Coinme and requires a physical location (i.e. selling crypto for cash) | | `quoteInput.promoCode` | `string` | No | | | `quoteInput.providerId` | `string` | Yes | | | `rampId` | `string` | No | | | `sourceWalletAddress` | `string` | No | Applicable for SELL flow only when selling from an external wallet (not custodied by Coinme), indicates from what wallet address is crypto sent | | `tags` | `string[]` | No | Optional - tags can be used to mark a transaction with unique keywords | | `webSessionId` | `string` | No | Optional - field is required only if partner is provisioned to have Coinme digital transaction processing screened by a security provider | ### CreateTransactionRequest Request for `POST /services/transaction`: Initiate Buy/Sell Transaction with Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `bankPaymentRail` | `'ACH_STANDARD' \| 'ACH_SAMEDAY' \| 'RTP' \| 'DOMESTIC_FED_WIRE'` | No | | | `bankTransferBeneficiaryId` | `string` | No | | | `bankTransferDetails` | `object` | No | | | `bankTransferDetails.achAddenda` | `string` | No | | | `bankTransferDetails.rtpRemittanceData` | `string` | No | | | `bankTransferDetails.wireOriginatorToBeneficiary` | `string` | No | | | `customerId` | `string` | Yes | Unique customer identifier | | `externalCustodyCreditInfo` | `object` | No | Applicable for BUY flow only when sending to an external wallet (not custodied by Coinme), details for sending crypto to external wallet | | `externalCustodyCreditInfo.blockchainMemo` | `string` | No | Blockchain memo for transaction (if applicable) | | `externalCustodyCreditInfo.walletAddress` | `string` | Yes | Wallet address to send crypto to. Required for external crypto deposit | | `externalSessionId` | `string` | No | | | `originatorNumOwner` | `'COINME' \| 'PARTNER' \| 'USER'` | No | | | `partnerTransactionId` | `string` | No | Automatically generated if not provided | | `paymentMethodId` | `string` | No | ID of payment method to buy or sell with (given in Add New Payment Method response). Required when using payment processing through Coinme | | `quoteId` | `string` | Yes | Quote Identifier referring to the specific crypto quote | | `sourceWalletAddress` | `string` | No | Applicable for SELL flow only when selling from an external wallet (not custodied by Coinme), indicates from what wallet address is crypto sent | | `tags` | `string[]` | No | Can be used to mark a transaction with unique keywords | | `webSessionId` | `string` | No | To be provided when using Coinme payment processing | ### CreateQuoteAndTransactionResponse Response for `POST /services/quote-and-transaction`: Initiate Buy or Sell without Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authTimeoutMillis` | `number \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `feeCurrencyCode` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `partnerTransactionId` | `string \| null` | No | | | `promoCode` | `string \| null` | No | | | `spreadAmount` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | | `transactionStatus` | `'CREATED' \| 'AUTH_REQUIRED' \| null` | No | | | `usdFeesReference` | `object \| null` | No | | | `usdFeesReference.feeAssetId` | `string \| null` | No | | | `usdFeesReference.feesMap` | `Record \| null` | No | | | `usdFeesReference.total` | `string \| null` | No | | ### CreateTransactionResponse Response for `POST /services/transaction`: Initiate Buy/Sell Transaction with Quote. | Property | Type | Required | Description | | --- | --- | --- | --- | | `authTimeoutMillis` | `number \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `feeCurrencyCode` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `partnerTransactionId` | `string \| null` | No | | | `promoCode` | `string \| null` | No | | | `spreadAmount` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | | `transactionStatus` | `'CREATED' \| 'AUTH_REQUIRED' \| null` | No | | | `usdFeesReference` | `object \| null` | No | | | `usdFeesReference.feeAssetId` | `string \| null` | No | | | `usdFeesReference.feesMap` | `Record \| null` | No | | | `usdFeesReference.total` | `string \| null` | No | | ### SellAllRequest Request for `POST /services/cryptoquote/sell-all`: Initiate Sell All Transaction. | Property | Type | Required | Description | | --- | --- | --- | --- | | `chain` | `string` | No | Possible values are "XLM" or "ETH". use only if Coinme supports trading this currency on multiple chains. otherwise unnecessary | | `creditCurrencyCode` | `string` | Yes | Credit currency code (i.e. DOGE) | | `cryptoSettlementType` | `'INTERNAL' \| 'EXTERNAL'` | No | Possible values are "INTERNAL" or "EXTERNAL". defaults to "INTERNAL". Use "EXTERNAL" to also calculate blockchain fees | | `customerId` | `string` | Yes | Unique customer identifier | | `debitCurrencyCode` | `string` | Yes | Debit currency code (i.e. USD) | | `latitude` | `number` | No | | | `locationReference` | `string` | No | | | `longitude` | `number` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread'` | No | | | `providerId` | `string` | No | | | `rampId` | `string` | No | | | `userQuoteLocation` | `object` | No | | | `userQuoteLocation.address1` | `string` | No | | | `userQuoteLocation.address2` | `string` | No | | | `userQuoteLocation.city` | `string` | No | | | `userQuoteLocation.coordinates` | `object` | No | | | `userQuoteLocation.coordinates.latitude` | `number` | Yes | | | `userQuoteLocation.coordinates.longitude` | `number` | Yes | | | `userQuoteLocation.country` | `string` | No | | | `userQuoteLocation.description` | `string` | No | | | `userQuoteLocation.locationReference` | `string` | No | | | `userQuoteLocation.state` | `string` | No | | | `userQuoteLocation.zipcode` | `string` | No | | ### SellAllResponse Response for `POST /services/cryptoquote/sell-all`: Initiate Sell All Transaction. | Property | Type | Required | Description | | --- | --- | --- | --- | | `chain` | `string \| null` | No | | | `creditCurrencyAmount` | `string \| null` | No | | | `creditCurrencyCode` | `string \| null` | No | | | `creditCurrencyUnitPrice` | `string \| null` | No | | | `creditCurrencyUnitPriceCode` | `string \| null` | No | | | `debitCurrencyAmount` | `string \| null` | No | | | `debitCurrencyCode` | `string \| null` | No | | | `debitCurrencyUnitPrice` | `string \| null` | No | | | `debitCurrencyUnitPriceCode` | `string \| null` | No | | | `expirationTime` | `string \| null` | No | Format: date-time. | | `expiresIn` | `number \| null` | No | | | `feeCurrency` | `string \| null` | No | | | `feesMap` | `Record \| null` | No | | | `promoCode` | `'noFees' \| 'noSpread' \| 'noFeesOrSpread' \| null` | No | | | `quoteId` | `string \| null` | No | | | `spread` | `string \| null` | No | | | `spreadCurrencyCode` | `string \| null` | No | | | `totalFees` | `string \| null` | No | | ### SubmitBlockchainIdRequest Request for `PUT /services/transaction/submit-blockchain-id`. | Property | Type | Required | Description | | --- | --- | --- | --- | | `blockchainTransactionId` | `string` | Yes | Onchain transaction hash of the sell order sent to Coinme | | `partnerTransactionId` | `string` | Yes | ID of the sell transaction from the transaction endpoint | | `refundWalletAddress` | `string` | No | address on which to execute refund to in case of transaction failure | ### SubmitBlockchainIdResponse Response for `PUT /services/transaction/submit-blockchain-id`. | Property | Type | Required | Description | | --- | --- | --- | --- | | `partnerTransactionId` | `string \| null` | No | | ### BaseQuoteBodyParams The quote details of a transaction created without an existing quote. ```typescript type BaseQuoteBodyParams = CreateQuoteAndTransactionRequest['quoteInput']; ``` ### ExternalCustodyCreditInfo Where crypto bought into an external wallet (not custodied by Coinme) is sent. ```typescript type ExternalCustodyCreditInfo = NonNullable; ``` ### FeesMap Fees for the transaction, by fee name. ```typescript type FeesMap = NonNullable; ``` ### GPSCoordinates GPS coordinates of a cash location. ```typescript type GPSCoordinates = NonNullable; ``` ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [P in keyof T]: T[P] | null }; ``` ### TransactionResponse The response to a buy or sell transaction, with or without an existing quote. ```typescript type TransactionResponse = CreateTransactionResponse; ``` ### 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 | | --- | --- | | `BuyBodyParams` | `CreateQuoteAndTransactionRequest` | | `BuyWithQuoteBodyParams` | `CreateTransactionRequest` | | `SellAllBodyParams` | `SellAllRequest` | | `SellBodyParams` | `CreateQuoteAndTransactionRequest` | | `SellWithQuoteBodyParams` | `CreateTransactionRequest` | ## 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[]` | 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/transactions-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- title: "History API client" url: "https://platformdocs.coinme.com/#/docs/caas-history-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-history-api-client.md" summary: "The `@coinme/history-api-client` package provides a client for interacting with the Coinme History APIs." surface: "caas" platform: "server" package: "@coinme/history-api-client" updated: "2026-11-04" --- # History API client The `@coinme/history-api-client` package provides a client for interacting with the Coinme History APIs. > **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/history-api-client@^2.0.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 interacting with the Coinme History APIs. ```typescript import { APIClient } from '@coinme/history-api-client'; const historyClient = 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 ### getAssetBalances Get asset balances for a given customer. ```typescript getAssetBalances(queryParams: GetAssetBalancesQuery): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `queryParams` | `GetAssetBalancesQuery` | The parameters required to fetch the asset balances. | A promise that resolves to a `GetAssetBalancesResponse`. See [GetAssetBalancesResponse](#getassetbalancesresponse), [GetAssetBalancesQuery](#getassetbalancesquery). ```typescript const response = await historyClient.getAssetBalances({ customerId: 'customer-id', estimatedBalanceCurrencyCode: 'USD', }); ``` ### getTransaction Get transaction details based on the `partnerTransactionId`. ```typescript getTransaction(partnerTransactionId: string): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `partnerTransactionId` | `string` | Unique identifier required for fetching the specific transaction. | A promise that resolves to the `GetTransactionResponse`, whose `transaction` holds the details. See [GetTransactionResponse](#gettransactionresponse). ```typescript const response = await historyClient.getTransaction('partner-transaction-id'); ``` ### getTransactionHistory Fetches the transaction history for a given customer. ```typescript getTransactionHistory(queryParams: GetTransactionHistoryQuery): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `queryParams` | `GetTransactionHistoryQuery` | The parameters required to fetch the transaction history. | A promise that resolves to a `GetTransactionHistoryResponse`. See [GetTransactionHistoryResponse](#gettransactionhistoryresponse), [GetTransactionHistoryQuery](#gettransactionhistoryquery). ```typescript const response = await historyClient.getTransactionHistory({ customerId: 'customer-id', }); ``` ### 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 historyClient.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. ### GetAssetBalancesQuery Query for `GET /services/cryptoassetbalance`: Get Crypto Asset Balance. | Property | Type | Required | Description | | --- | --- | --- | --- | | `customerId` | `string` | Yes | Unique customer identifier | | `estimatedBalanceCurrencyCode` | `string` | Yes | Currency code of the balance (i.e. USD) | ### GetAssetBalancesResponse Response for `GET /services/cryptoassetbalance`: Get Crypto Asset Balance. | Property | Type | Required | Description | | --- | --- | --- | --- | | `cryptoAssetsBalance` | `object[] \| null` | No | | | `cryptoAssetsBalance[].balance` | `string \| null` | No | | | `cryptoAssetsBalance[].currencyName` | `string \| null` | No | | | `cryptoAssetsBalance[].currencySymbol` | `string \| null` | No | | | `cryptoAssetsBalance[].estimatedBalanceValue` | `string \| null` | No | | | `cryptoAssetsBalance[].updatedAt` | `string \| null` | No | | ### GetTransactionHistoryQuery Query for `GET /services/transactionhistory`: Get Transaction History. | Property | Type | Required | Description | | --- | --- | --- | --- | | `currencyCode` | `string` | No | Currency code of the cryptocurrency (i.e. DOGE) | | `customerId` | `string` | Yes | Unique customer identifier | | `endDateTime` | `string` | No | UTC (i.e. 2022-01-24T16:44:49Z) | | `page` | `number` | No | Number of pages | | `size` | `number` | No | Page size (max value is 500) | | `startDateTime` | `string` | No | UTC (i.e. 2022-01-24T16:44:49Z) | ### GetTransactionHistoryResponse Response for `GET /services/transactionhistory`: Get Transaction History. | Property | Type | Required | Description | | --- | --- | --- | --- | | `transactions` | `object[] \| null` | No | | | `transactions[].bankPaymentRail` | `'ACH_STANDARD' \| 'ACH_SAMEDAY' \| 'RTP' \| 'DOMESTIC_FED_WIRE' \| null` | No | | | `transactions[].bankTransferBeneficiaryId` | `string \| null` | No | | | `transactions[].blockchainTransactionId` | `string \| null` | No | | | `transactions[].creditAssetId` | `string \| null` | No | | | `transactions[].creditCurrencyAmount` | `string \| null` | No | | | `transactions[].creditCurrencyChain` | `string \| null` | No | | | `transactions[].creditCurrencyCode` | `string \| null` | No | | | `transactions[].cryptoSettlementType` | `string \| null` | No | | | `transactions[].debitAssetId` | `string \| null` | No | | | `transactions[].debitCurrencyAmount` | `string \| null` | No | | | `transactions[].debitCurrencyChain` | `string \| null` | No | | | `transactions[].debitCurrencyCode` | `string \| null` | No | | | `transactions[].errorCode` | `string \| null` | No | | | `transactions[].externalSessionId` | `string \| null` | No | | | `transactions[].feeCurrencyCode` | `string \| null` | No | | | `transactions[].feesMap` | `Record \| null` | No | | | `transactions[].fiatFees` | `object \| null` | No | | | `transactions[].fiatFees.feeAssetId` | `string \| null` | No | | | `transactions[].fiatFees.feesMap` | `Record \| null` | No | | | `transactions[].fiatFees.total` | `string \| null` | No | | | `transactions[].imageUrl` | `string \| null` | No | | | `transactions[].location` | `object \| null` | No | | | `transactions[].location.address1` | `string \| null` | No | | | `transactions[].location.address2` | `string \| null` | No | | | `transactions[].location.city` | `string \| null` | No | | | `transactions[].location.coordinates` | `object \| null` | No | | | `transactions[].location.coordinates.latitude` | `number \| null` | No | | | `transactions[].location.coordinates.longitude` | `number \| null` | No | | | `transactions[].location.country` | `string \| null` | No | | | `transactions[].location.description` | `string \| null` | No | | | `transactions[].location.locationReference` | `string \| null` | No | | | `transactions[].location.state` | `string \| null` | No | | | `transactions[].location.zipCode` | `string \| null` | No | | | `transactions[].orderType` | `string \| null` | No | | | `transactions[].originatorNumOwner` | `'COINME' \| 'PARTNER' \| 'USER' \| null` | No | | | `transactions[].partnerTransactionId` | `string \| null` | No | | | `transactions[].paymentMethodId` | `string \| null` | No | | | `transactions[].promoCode` | `string \| null` | No | | | `transactions[].providerId` | `string \| null` | No | | | `transactions[].providerTransactionId` | `string \| null` | No | | | `transactions[].providerTransactionRef` | `string \| null` | No | | | `transactions[].spreadAmount` | `string \| null` | No | | | `transactions[].spreadCurrencyCode` | `string \| null` | No | | | `transactions[].tags` | `string[] \| null` | No | | | `transactions[].totalFees` | `string \| null` | No | | | `transactions[].trackingInfo` | `object \| null` | No | | | `transactions[].trackingInfo.orderUpdateDateTime` | `string \| null` | No | | | `transactions[].trackingInfo.trackingComplete` | `boolean \| null` | No | | | `transactions[].trackingInfo.trackingState` | `string \| null` | No | | | `transactions[].trackingInfo.trackingStateDescription` | `string \| null` | No | | | `transactions[].trackingInfo.trackingType` | `string \| null` | No | | | `transactions[].transactionDateTime` | `string \| null` | No | | | `transactions[].transactionStatus` | `'PENDING' \| 'BLOCKCHAIN_ACCEPTED' \| 'CONFIRMED' \| 'FAILED' \| null` | No | | ### GetTransactionPathParams PathParams for `GET /services/transactions/{partnerTransactionID}`: Get Specific Transaction. | Property | Type | Required | Description | | --- | --- | --- | --- | | `partnerTransactionID` | `string` | Yes | | ### GetTransactionResponse Response for `GET /services/transactions/{partnerTransactionID}`: Get Specific Transaction. | Property | Type | Required | Description | | --- | --- | --- | --- | | `transaction` | `object \| null` | No | | | `transaction.bankPaymentRail` | `'ACH_STANDARD' \| 'ACH_SAMEDAY' \| 'RTP' \| 'DOMESTIC_FED_WIRE' \| null` | No | | | `transaction.bankTransferBeneficiaryId` | `string \| null` | No | | | `transaction.blockchainTransactionId` | `string \| null` | No | | | `transaction.creditAssetId` | `string \| null` | No | | | `transaction.creditCurrencyAmount` | `string \| null` | No | | | `transaction.creditCurrencyChain` | `string \| null` | No | | | `transaction.creditCurrencyCode` | `string \| null` | No | | | `transaction.cryptoSettlementType` | `string \| null` | No | | | `transaction.debitAssetId` | `string \| null` | No | | | `transaction.debitCurrencyAmount` | `string \| null` | No | | | `transaction.debitCurrencyChain` | `string \| null` | No | | | `transaction.debitCurrencyCode` | `string \| null` | No | | | `transaction.errorCode` | `string \| null` | No | | | `transaction.externalSessionId` | `string \| null` | No | | | `transaction.feeCurrencyCode` | `string \| null` | No | | | `transaction.feesMap` | `Record \| null` | No | | | `transaction.fiatFees` | `object \| null` | No | | | `transaction.fiatFees.feeAssetId` | `string \| null` | No | | | `transaction.fiatFees.feesMap` | `Record \| null` | No | | | `transaction.fiatFees.total` | `string \| null` | No | | | `transaction.imageUrl` | `string \| null` | No | | | `transaction.location` | `object \| null` | No | | | `transaction.location.address1` | `string \| null` | No | | | `transaction.location.address2` | `string \| null` | No | | | `transaction.location.city` | `string \| null` | No | | | `transaction.location.coordinates` | `object \| null` | No | | | `transaction.location.coordinates.latitude` | `number \| null` | No | | | `transaction.location.coordinates.longitude` | `number \| null` | No | | | `transaction.location.country` | `string \| null` | No | | | `transaction.location.description` | `string \| null` | No | | | `transaction.location.locationReference` | `string \| null` | No | | | `transaction.location.state` | `string \| null` | No | | | `transaction.location.zipCode` | `string \| null` | No | | | `transaction.orderType` | `string \| null` | No | | | `transaction.originatorNumOwner` | `'COINME' \| 'PARTNER' \| 'USER' \| null` | No | | | `transaction.partnerTransactionId` | `string \| null` | No | | | `transaction.paymentMethodId` | `string \| null` | No | | | `transaction.promoCode` | `string \| null` | No | | | `transaction.providerId` | `string \| null` | No | | | `transaction.providerTransactionId` | `string \| null` | No | | | `transaction.providerTransactionRef` | `string \| null` | No | | | `transaction.spreadAmount` | `string \| null` | No | | | `transaction.spreadCurrencyCode` | `string \| null` | No | | | `transaction.tags` | `string[] \| null` | No | | | `transaction.totalFees` | `string \| null` | No | | | `transaction.trackingInfo` | `object \| null` | No | | | `transaction.trackingInfo.orderUpdateDateTime` | `string \| null` | No | | | `transaction.trackingInfo.trackingComplete` | `boolean \| null` | No | | | `transaction.trackingInfo.trackingState` | `string \| null` | No | | | `transaction.trackingInfo.trackingStateDescription` | `string \| null` | No | | | `transaction.trackingInfo.trackingType` | `string \| null` | No | | | `transaction.transactionDateTime` | `string \| null` | No | | | `transaction.transactionStatus` | `'PENDING' \| 'BLOCKCHAIN_ACCEPTED' \| 'CONFIRMED' \| 'FAILED' \| null` | No | | ### CryptoAssetsBalance One crypto asset balance in a `GetAssetBalancesResponse`. ```typescript type CryptoAssetsBalance = NonNullable[number]; ``` ### GPSCoordinates GPS coordinates of a location. ```typescript type GPSCoordinates = NonNullable; ``` ### LocationInfo Where a cash transaction took place. ```typescript type LocationInfo = NonNullable; ``` ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [P in keyof T]: T[P] | null }; ``` ### OrderTrackingInfo Tracking details of an order. ```typescript type OrderTrackingInfo = NonNullable; ``` ### Transaction One transaction in a `GetTransactionHistoryResponse`. ```typescript type Transaction = NonNullable[number]; ``` ### TransactionDetails The transaction in a `GetTransactionResponse`. ```typescript type TransactionDetails = NonNullable; ``` ### 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 | | --- | --- | | `CryptoAssetsBalancesQueryParams` | `GetAssetBalancesQuery` | | `GetTransactionHistoryQueryParams` | `GetTransactionHistoryQuery` | ## 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[]` | 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/history-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- title: "Locations API client" url: "https://platformdocs.coinme.com/#/docs/caas-locations-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-locations-api-client.md" summary: "The `@coinme/locations-api-client` package provides a client for interacting with the Coinme Locations APIs." surface: "caas" platform: "server" package: "@coinme/locations-api-client" updated: "2026-11-04" --- # Locations API client The `@coinme/locations-api-client` package provides a client for interacting with the Coinme Locations APIs. > **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/locations-api-client@^2.0.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 interacting with the Coinme Locations APIs. ```typescript import { APIClient } from '@coinme/locations-api-client'; const locationsClient = 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 ### getLocationLicensing Get a list of states where Coinme is approved to operate in. ```typescript getLocationLicensing(countryCode: string): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `countryCode` | `string` | The country code to get the licensing for. | A promise that resolves to a `GetLocationLicensingResponse`. See [GetLocationLicensingResponse](#getlocationlicensingresponse). ```typescript const response = await locationsClient.getLocationLicensing('US'); ``` ### 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 locationsClient.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. ### GetLocationLicensingQuery Query for `GET /services/locationlicensing`: Get Location Licensing. | Property | Type | Required | Description | | --- | --- | --- | --- | | `country` | `string` | Yes | | ### GetLocationLicensingResponse Response for `GET /services/locationlicensing`: Get Location Licensing. | Property | Type | Required | Description | | --- | --- | --- | --- | | `locations` | `string[] \| null` | No | | ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [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[]` | 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/locations-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- title: "Send API client" url: "https://platformdocs.coinme.com/#/docs/caas-send-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-send-api-client.md" summary: "The `@coinme/send-api-client` package provides a client for interacting with the Coinme Send APIs." surface: "caas" platform: "server" package: "@coinme/send-api-client" updated: "2026-11-04" --- # Send API client The `@coinme/send-api-client` package provides a client for interacting with the Coinme Send APIs. > **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/send-api-client@^2.0.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 interacting with the Coinme Send APIs. ```typescript import { APIClient } from '@coinme/send-api-client'; const sendClient = 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 ### send Send a specified amount of crypto to an external wallet address. ```typescript send(body: SendRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `SendRequest` | The request body containing the parameters needed for a send transaction. | A promise that resolves to the `SendResponse`. See [SendResponse](#sendresponse), [SendRequest](#sendrequest). ```typescript const response = await sendClient.send({ amount: '100', currency: 'USD', 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 sendClient.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. ### 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 | | ### 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 | | --- | --- | | `SendBodyParams` | `SendRequest` | ## 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[]` | 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/send-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- 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 ``` | 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 ``` | 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 ``` | 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 ``` 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 ``` | 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 ``` | 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 ``` | 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 = { [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[]` | 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; } ``` --- --- title: "Cash ramp API client" url: "https://platformdocs.coinme.com/#/docs/caas-cash-ramp-api-client" markdown: "https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md" summary: "The `@coinme/cash-ramp-api-client` package provides a client for interacting with the Coinme cash on and off ramp APIs: cash locations and order templates. An order template is the barcode a customer presents at a cash location to buy or sell crypto with cash." surface: "caas" platform: "server" package: "@coinme/cash-ramp-api-client" updated: "2026-11-04" --- # Cash ramp API client The `@coinme/cash-ramp-api-client` package provides a client for interacting with the Coinme cash on and off ramp APIs: cash locations and order templates. An order template is the barcode a customer presents at a cash location to buy or sell crypto with cash. > **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/cash-ramp-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 cash on and off ramp APIs: cash locations and order templates (the barcodes customers present at a location). ```typescript import { APIClient } from '@coinme/cash-ramp-api-client'; const cashRampClient = 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 ### createOrderTemplate Creates an order template, the barcode a customer presents at a cash location. ```typescript createOrderTemplate(body: CreateOrderTemplateRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `CreateOrderTemplateRequest` | The customer, the currencies and amount, the provider and the location. | A promise that resolves to the `CreateOrderTemplateResponse`. See [CreateOrderTemplateResponse](#createordertemplateresponse), [CreateOrderTemplateRequest](#createordertemplaterequest). ```typescript const response = await cashRampClient.createOrderTemplate({ amountCurrencyCode: 'USD', amountValue: '100', creditCurrencyCode: 'BTC', customerId: 'customer-id', debitCurrencyCode: 'USD', locationReference: 'location-reference', providerId: 'provider-id', }); ``` ### deleteOrderTemplate Invalidates an order template. Only a template in the CREATED or UPDATED status can be deleted. ```typescript deleteOrderTemplate(orderTemplateId: string, query: DeleteOrderTemplateQuery): Promise<'Deleted'> ``` | Parameter | Type | Description | | --- | --- | --- | | `orderTemplateId` | `string` | The order template. | | `query` | `DeleteOrderTemplateQuery` | The customer it belongs to. | A promise that resolves to the `DeleteOrderTemplateResponse`. See [DeleteOrderTemplateQuery](#deleteordertemplatequery). ```typescript const response = await cashRampClient.deleteOrderTemplate('order-template-id', { customerId: 'customer-id', }); ``` ### getOrderTemplateCount Returns how many active order templates a customer has with a provider, and whether the limit is reached. ```typescript getOrderTemplateCount(accountId: string, query: GetOrderTemplateCountQuery): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `accountId` | `string` | The customer. | | `query` | `GetOrderTemplateCountQuery` | The provider. | A promise that resolves to the `GetOrderTemplateCountResponse`. See [GetOrderTemplateCountResponse](#getordertemplatecountresponse), [GetOrderTemplateCountQuery](#getordertemplatecountquery). ```typescript const response = await cashRampClient.getOrderTemplateCount('account-id', { providerId: 'provider-id', }); ``` ### getOrderTemplates Returns the order templates of a customer. ```typescript getOrderTemplates(accountId: string, query?: GetOrderTemplatesQuery): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `accountId` | `string` | The customer. | | `query?` | `GetOrderTemplatesQuery` | Optional paging. | A promise that resolves to the `GetOrderTemplatesResponse`. See [GetOrderTemplatesResponse](#getordertemplatesresponse), [GetOrderTemplatesQuery](#getordertemplatesquery). ```typescript const response = await cashRampClient.getOrderTemplates('account-id'); ``` ### queryLocations Returns the cash ramp locations nearest to a point, sorted by distance. ```typescript queryLocations(body: QueryLocationsRequest): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `body` | `QueryLocationsRequest` | The point, the radius and optional filters. | A promise that resolves to the `QueryLocationsResponse`. See [QueryLocationsResponse](#querylocationsresponse), [QueryLocationsRequest](#querylocationsrequest). ```typescript const response = await cashRampClient.queryLocations({ latitude: 1, longitude: 1, radius: 1, }); ``` ### refreshOrderTemplate Creates a new order template with the same parameters as an existing one. ```typescript refreshOrderTemplate(refreshOrderTemplateId: string): Promise ``` | Parameter | Type | Description | | --- | --- | --- | | `refreshOrderTemplateId` | `string` | The id of the order template to renew. | A promise that resolves to the `RefreshOrderTemplateResponse`. See [RefreshOrderTemplateResponse](#refreshordertemplateresponse). ```typescript const response = await cashRampClient.refreshOrderTemplate('refresh-order-template-id'); ``` ### 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 cashRampClient.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. ### CreateOrderTemplateRequest Request for `POST /services/order-template`: Generate Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `amountCurrencyCode` | `string` | Yes | Currency code of amount (i.e. USD) | | `amountValue` | `string` | Yes | Amount to buy | | `chain` | `string` | No | Crypto chain the crypto will be sent on. Possible values are "XLM", "ETH", "LINEA" or "SOL". Use only if Coinme supports trading this currency on multiple chains. otherwise unnecessary | | `creditCurrencyCode` | `string` | Yes | Credit currency code (i.e. DOGE) | | `customerId` | `string` | Yes | Unique customer identifier | | `debitCurrencyCode` | `string` | Yes | Debit currency code (i.e. USD) | | `externalCustodyCreditInfo` | `object` | No | | | `externalCustodyCreditInfo.blockchainMemo` | `string` | No | Blockchain memo for transaction (if applicable) | | `externalCustodyCreditInfo.walletAddress` | `string` | Yes | Wallet address to send crypto to. Required for external crypto deposit | | `gpsCoordinates` | `object` | No | | | `gpsCoordinates.latitude` | `number` | No | | | `gpsCoordinates.longitude` | `number` | No | | | `isLedgerSend` | `boolean` | No | | | `locationReference` | `string` | Yes | Encoded reference of the location | | `providerId` | `string` | Yes | ID of payment provider (provided by Coinme) | | `rampId` | `string` | No | | ### CreateOrderTemplateResponse Response for `POST /services/order-template`: Generate Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `transactionTemplate` | `object \| null` | No | | | `transactionTemplate.active` | `boolean \| null` | No | | | `transactionTemplate.amountCurrencyCode` | `string \| null` | No | | | `transactionTemplate.amountValue` | `string \| null` | No | | | `transactionTemplate.chain` | `string \| null` | No | | | `transactionTemplate.creditAssetId` | `string \| null` | No | | | `transactionTemplate.creditCurrencyAmount` | `string \| null` | No | | | `transactionTemplate.creditCurrencyCode` | `string \| null` | No | | | `transactionTemplate.debitAssetId` | `string \| null` | No | | | `transactionTemplate.debitCurrencyCode` | `string \| null` | No | | | `transactionTemplate.debitCurrencyUnitPrice` | `string \| null` | No | | | `transactionTemplate.expiryTimestamp` | `string \| null` | No | | | `transactionTemplate.feesMap` | `Record \| null` | No | | | `transactionTemplate.orderType` | `string \| null` | No | | | `transactionTemplate.providerExclusiveFees` | `Record \| null` | No | | | `transactionTemplate.refreshedFromOrderTemplateId` | `string \| null` | No | | | `transactionTemplate.sealed` | `boolean \| null` | No | | | `transactionTemplate.spreadAmount` | `string \| null` | No | | | `transactionTemplate.spreadCurrencyCode` | `string \| null` | No | | | `transactionTemplate.transactionProviderRef` | `string \| null` | No | | | `transactionTemplate.transactionSystemRef` | `string \| null` | No | The order template's id, the one `deleteOrderTemplate` takes. | ### DeleteOrderTemplateQuery Query for `DELETE /services/order-template/{orderTemplateId}`: Delete Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `customerId` | `string` | Yes | Unique customer identifier | | `note` | `string` | No | | ### GetOrderTemplateCountQuery Query for `GET /services/order-template/templates/count/{accountId}`: Get Order Templates Count. | Property | Type | Required | Description | | --- | --- | --- | --- | | `providerId` | `string` | Yes | ID of payment provider (provided by Coinme) | ### GetOrderTemplateCountResponse Response for `GET /services/order-template/templates/count/{accountId}`: Get Order Templates Count. | Property | Type | Required | Description | | --- | --- | --- | --- | | `createdCount` | `number \| null` | No | | | `maximumReached` | `boolean \| null` | No | | | `maxOrdersSubmitted` | `number \| null` | No | | ### GetOrderTemplatesQuery Query for `GET /services/order-template/templates/{accountId}`: Get Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `page` | `number` | No | | | `size` | `number` | No | | ### GetOrderTemplatesResponse Response for `GET /services/order-template/templates/{accountId}`: Get Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `page` | `number \| null` | No | | | `size` | `number \| null` | No | | | `totalElements` | `number \| null` | No | | | `totalPages` | `number \| null` | No | | | `transactionTemplate` | `object[] \| null` | No | | | `transactionTemplate[].active` | `boolean \| null` | No | | | `transactionTemplate[].amountCurrencyCode` | `string \| null` | No | | | `transactionTemplate[].amountValue` | `string \| null` | No | | | `transactionTemplate[].chain` | `string \| null` | No | | | `transactionTemplate[].creditAssetId` | `string \| null` | No | | | `transactionTemplate[].creditCurrencyAmount` | `string \| null` | No | | | `transactionTemplate[].creditCurrencyCode` | `string \| null` | No | | | `transactionTemplate[].debitAssetId` | `string \| null` | No | | | `transactionTemplate[].debitCurrencyCode` | `string \| null` | No | | | `transactionTemplate[].feesMap` | `Record \| null` | No | | | `transactionTemplate[].locationData` | `object \| null` | No | | | `transactionTemplate[].locationData.address1` | `string \| null` | No | | | `transactionTemplate[].locationData.address2` | `string \| null` | No | | | `transactionTemplate[].locationData.city` | `string \| null` | No | | | `transactionTemplate[].locationData.coordinates` | `object \| null` | No | | | `transactionTemplate[].locationData.coordinates.latitude` | `number \| null` | No | | | `transactionTemplate[].locationData.coordinates.longitude` | `number \| null` | No | | | `transactionTemplate[].locationData.country` | `string \| null` | No | | | `transactionTemplate[].locationData.description` | `string \| null` | No | | | `transactionTemplate[].locationData.locationReference` | `string \| null` | No | | | `transactionTemplate[].locationData.state` | `string \| null` | No | | | `transactionTemplate[].locationData.zipCode` | `string \| null` | No | | | `transactionTemplate[].locationReference` | `string \| null` | No | | | `transactionTemplate[].orderType` | `string \| null` | No | | | `transactionTemplate[].providerExclusiveFees` | `Record \| null` | No | | | `transactionTemplate[].refreshedFromOrderTemplateId` | `string \| null` | No | | | `transactionTemplate[].sealed` | `boolean \| null` | No | | | `transactionTemplate[].spreadAmount` | `string \| null` | No | | | `transactionTemplate[].spreadCurrencyCode` | `string \| null` | No | | | `transactionTemplate[].status` | `'CREATED' \| 'UPDATED' \| 'CONSUMED' \| 'COMPLETED' \| 'REJECTED' \| 'EXPIRED' \| 'DELETED' \| null` | No | | | `transactionTemplate[].timestamp` | `string \| null` | No | | | `transactionTemplate[].transactionProviderRef` | `string \| null` | No | | | `transactionTemplate[].transactionSystemRef` | `string \| null` | No | The order template's id, the one `deleteOrderTemplate` takes. | ### QueryLocationsRequest Request for `POST /services/locations/v2/query`: Get Cash Ramp Locations. | Property | Type | Required | Description | | --- | --- | --- | --- | | `coins` | `string[]` | No | | | `distanceUnit` | `string` | No | | | `latitude` | `number` | Yes | Latitude of the user's location for searching nearby locations | | `limit` | `number` | No | Maximum number of location results to return | | `longitude` | `number` | Yes | Longitude of the user's location for searching nearby locations | | `providers` | `string[]` | No | Array of provider names to filter results, Current providers are greendot | | `radius` | `number` | Yes | Search radius in specified units (miles/kilometers, defaults to miles) | ### QueryLocationsResponse Response for `POST /services/locations/v2/query`: Get Cash Ramp Locations. | Property | Type | Required | Description | | --- | --- | --- | --- | | `locations` | `object[] \| null` | No | | | `locations[].address` | `string \| null` | No | | | `locations[].buyAllowed` | `boolean \| null` | No | | | `locations[].city` | `string \| null` | No | | | `locations[].coordinates` | `object \| null` | No | | | `locations[].coordinates.latitude` | `number \| null` | No | | | `locations[].coordinates.longitude` | `number \| null` | No | | | `locations[].country` | `string \| null` | No | | | `locations[].description` | `string \| null` | No | | | `locations[].googlePlacesLink` | `string \| null` | No | | | `locations[].hours` | `Record \| null` | No | | | `locations[].id` | `string \| null` | No | | | `locations[].imageUrl` | `string \| null` | No | | | `locations[].lineOfSightDistance` | `number \| null` | No | | | `locations[].lineOfSightMetric` | `string \| null` | No | | | `locations[].locationFees` | `Record \| null` | No | | | `locations[].locationReference` | `string \| null` | No | | | `locations[].metadata` | `Record \| null` | No | | | `locations[].notes` | `string \| null` | No | | | `locations[].provider` | `string \| null` | No | | | `locations[].sellAllowed` | `boolean \| null` | No | | | `locations[].state` | `string \| null` | No | | | `locations[].supportedCoins` | `object[] \| null` | No | | | `locations[].supportedCoins[].acronym` | `string \| null` | No | | | `locations[].supportedCoins[].name` | `string \| null` | No | | | `locations[].zipCode` | `string \| null` | No | | | `providers` | `string[] \| null` | No | | ### RefreshOrderTemplateResponse Response for `GET /services/order-template/refresh`: Regenerate Order Template. | Property | Type | Required | Description | | --- | --- | --- | --- | | `transactionTemplate` | `object \| null` | No | | | `transactionTemplate.active` | `boolean \| null` | No | | | `transactionTemplate.amountCurrencyCode` | `string \| null` | No | | | `transactionTemplate.amountValue` | `string \| null` | No | | | `transactionTemplate.chain` | `string \| null` | No | | | `transactionTemplate.creditAssetId` | `string \| null` | No | | | `transactionTemplate.creditCurrencyAmount` | `string \| null` | No | | | `transactionTemplate.creditCurrencyCode` | `string \| null` | No | | | `transactionTemplate.debitAssetId` | `string \| null` | No | | | `transactionTemplate.debitCurrencyCode` | `string \| null` | No | | | `transactionTemplate.debitCurrencyUnitPrice` | `string \| null` | No | | | `transactionTemplate.expiryTimestamp` | `string \| null` | No | | | `transactionTemplate.feesMap` | `Record \| null` | No | | | `transactionTemplate.orderType` | `string \| null` | No | | | `transactionTemplate.providerExclusiveFees` | `Record \| null` | No | | | `transactionTemplate.refreshedFromOrderTemplateId` | `string \| null` | No | | | `transactionTemplate.sealed` | `boolean \| null` | No | | | `transactionTemplate.spreadAmount` | `string \| null` | No | | | `transactionTemplate.spreadCurrencyCode` | `string \| null` | No | | | `transactionTemplate.transactionProviderRef` | `string \| null` | No | | | `transactionTemplate.transactionSystemRef` | `string \| null` | No | The order template's id, the one `deleteOrderTemplate` takes. | ### DeleteOrderTemplateResponse Response for `DELETE /services/order-template/{orderTemplateId}`: Delete Order Template. ```typescript type DeleteOrderTemplateResponse = 'Deleted'; ``` ### Nullable A type that represents a nullable version of the given type. ```typescript type Nullable = { [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[]` | 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/cash-ramp-api-client'; try { // a call on the client } catch (error) { if (isAPIError(error)) { console.error(error.errorResponse.httpStatus, error.errorResponse.errorData); } throw error; } ``` --- --- 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-.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)