---
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<CreateOrderTemplateResponse>
```

| 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<GetOrderTemplateCountResponse>
```

| 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<GetOrderTemplatesResponse>
```

| 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<QueryLocationsResponse>
```

| 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<RefreshOrderTemplateResponse>
```

| 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<string, string> \| null` | No |  |
| `transactionTemplate.orderType` | `string \| null` | No |  |
| `transactionTemplate.providerExclusiveFees` | `Record<string, { amount?: string \| null; assetId?: string \| null; chain?: string \| null; currency?: string \| null }> \| 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<string, string> \| 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<string, { amount?: string \| null; assetId?: string \| null; chain?: string \| null; currency?: string \| null }> \| 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<string, string> \| 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<string, string> \| null` | No |  |
| `locations[].locationReference` | `string \| null` | No |  |
| `locations[].metadata` | `Record<string, unknown> \| 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<string, string> \| null` | No |  |
| `transactionTemplate.orderType` | `string \| null` | No |  |
| `transactionTemplate.providerExclusiveFees` | `Record<string, { amount?: string \| null; assetId?: string \| null; chain?: string \| null; currency?: string \| null }> \| 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<T> = { [P in keyof T]: T[P] | null };
```

## Errors

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

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

### CAASErrorResponse

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

### CAASErrorData

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

```typescript
import { isAPIError } from '@coinme/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;
}
```
