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

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

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

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

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

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

| 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<string, string> \| 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<string, string> \| 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<string, string> \| 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<string, string> \| 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<string, string> \| 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<CreateTransactionRequest['externalCustodyCreditInfo']>;
```

### FeesMap

Fees for the transaction, by fee name.

```typescript
type FeesMap = NonNullable<TransactionResponse['feesMap']>;
```

### GPSCoordinates

GPS coordinates of a cash location.

```typescript
type GPSCoordinates = NonNullable<BaseQuoteBodyParams['gpsCoordinates']>;
```

### Nullable

A type that represents a nullable version of the given type.

```typescript
type Nullable<T> = { [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<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/transactions-api-client';

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