The Coinpayments API documentation defines a standard, language-agnostic interface to the CoinPayments API. The platform allows merchants to integrate the payment system into their own websites or applications, enabling their customers to pay for goods or services with cryptocurrency. The API documentation provides the necessary information for developers to integrate the payment system into their own platforms, including details on how to authenticate requests, what parameters to include in requests. response schemas, error handling, and implementation examples. Overall, the API is designed to provide a simple and secure way for merchants to accept cryptocurrency payments from their customers. Within this documentation you'll find everything you need to leverage CoinPayments for your service.

While reviewing the documentation, it is advised to explore requests within Postman.

View the following page for more information on Getting started with Postman.

To create test transactions, you can use LTCT coins.

To claim LTCT, click on the "Get Free LTCT" button next to the corresponding coin balance within the CoinPayments dashboard.

CoinPayments provides a multi-currency wallet that enables businesses and individuals to store, send, and receive a wide range of digital currencies and tokens. The free-to-set-up wallet is available on web and mobile, enabling account management online and on the go. Generate versatile invoices for a wide range of cryptocurrencies with real-time updates on payment status.

Some of the key features of the system include:

• Currencies
• Rates
• Fees
• Wallets
• Transactions
• Invoices
• Webhooks

In this section you will find ready-made code examples for the most frequent use-cases.

See examples of how to create invoices with CPS API:

• create invoice in PHP using CPS v2 API
• create invoice in C# using CPS v2 API

QR Code Generation

A merchant can simplify the payment process for the buyer by incorporating payment details like payment amount, currency and payment address into a QR code. Below is an example of a script to create a QR code:

<div id="canvas"></div>
<script type="text/javascript" src="https://unpkg.com/qr-code-styling@1.5.0/lib/qr-code-styling.js"></script>
<script type="text/javascript">
  const generateQRData = (currency, address, tag, amount) => {
    switch (currency.name) {
      case 'Bitcurrency SV':
        return `bitcurrency:${address}?sv&amount=${amount}`;
      case 'Tether USD (Omni)':
        return `bitcurrency:${address}?amount=${amount}&req-asset=${currency.id}`;
      case 'BinanceCoin':
        return `bnb:${address}?sv&amount=${amount}&req-asset=${currency.id}`;
      case 'Tether USD (ERC20)':
        return `ethereum:${address}?value=${amount}&req-asset=${currency.id.slice(currency.id.indexOf(':') + 1)}`;
      case 'Tether USD (TRC20)':
        return `tron:${address}?value=${amount}&req-asset=${currency.id.slice(currency.id.indexOf(':') + 1)}`;
      default:
        return `${currency?.name?.toLowerCase().replace(/ /g, '')}:${address}?amount=${amount}${tag ? `&tag=${tag}` : ''}`;
    }
  };

  const color = "#2A5ED5";
  const corner = "#000000";
  const margin = 5;

  const qrCode = new QRCodeStyling({
    width: 200,
    height: 200,
    dotsOptions: {
      color: color,
      type: "square"
    },
    backgroundOptions: {
      color: "transparent",
      gradient: null
    },
    cornersSquareOptions: {
      type: "square",
      color: corner
    },
    cornersDotOptions: {
      type: "square",
      color: corner
    },
    imageOptions: {
      crossOrigin: "anonymous",
      imageSize: 0.5,
      margin: margin
    }
  });

  qrCode.append(document.querySelector('#canvas'));
  qrCode.update({
    data: generateQRData(currency, address, tag, amount)
  });
  </script>

Withdrawals and Deposits

See our C# example of a webhook for a deposit transaction.

Also, see how to prove the authentication of the webhook received from CPS here.

Invoices

Here you can find an example of how to check all the available webhook subscriptions for invoices and prove their authentication in PHP.

See this C# V2 API example to learn how to check the current blockchain network fee for a particular cryptocurrency.

This section provides an overview of the common errors that you may encounter when utilizing the CoinPayments API. By familiarizing yourself with these errors, you will be better equipped to handle potential issues and troubleshoot effectively. Understanding these errors will contribute to a smoother integration process and ensure a more seamless payment experience for your users.

Unauthorized (401)

This error occurs when user authorization fails due to an invalid API signature.

Common issues causing this error:

• An invalid clientId or clientSecret.
• The integration has been deleted on the dashboard.
• The API signature is not constructed properly.

Please see Authenticating with the API and Generating API request signature for more information.

Bad Request (400)

This error occurs when there is an issue validating the provided data for the requested resource.

Ensure you are sending all required parameters with the correct type by referencing the specific route documentation.

Within the API response you will find a description of the applicable validation error for the request.

Insufficient Funds

This error can occur when withdrawing funds to an external address, or when converting currencies.

This is caused by the user's wallet not having a sufficient balance to cover the transaction amount and any applicable fees.

Invalid Address

When creating a transaction for a withdrawal or conversion, if the provided address is not valid or formatted correctly, this error is triggered. Users should ensure the address they provided follows the required format.

Examples of valid addresses:

Valid UTXO-Based Coin Addresses:

• Bitcoin (BTC): 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
• Bitcoin Cash (BCH): bitcoincash:qr7uq7uvujmzhcv29tw92q0hs7fwpht4fvl4a4kj9a
• Litecoin (LTC): LZx9pzGfH6mKSzVsJZnryeVrRzt6X8uZ9r

Valid Token Coin Addresses:

• Ethereum (ETH): 0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf
• ERC-20 Tokens (e.g., DAI, USDT): 0x6B175474E89094C44Da98b954EedeAC495271d0F

Invalid or Unsupported Currency

This error occurs when the API request involves an invalid or unsupported currency.

Please see Supported Currencies for more information.

The API has a default rate limit of 70 requests per second.

Rate limits have been implemented to prevent abuse and ensure the stability and optimal performance of our systems.

If you are encountering issues with this limitation, please Contact us to discuss your integration further.

The CoinPayments API uses a hash-based message authentication code (HMAC) in Base64 format that employs the SHA-256 algorithm to authenticate requests.

The client generates a unique HMAC signature for each request using the client secret and incorporating the following request data:

• \ufeff (Byte Order Mark)
• HTTP method
• URL
• Integration Client ID
• Timestamp (UTC ISO)
• Request payload (JSON)

See the Generate API Signature section for more information.

Note: Limited select endpoints do not require authentication. (currencies, rates, fees)

Every client secret is associated with an integration created on the CoinPayments dashboard.

In order to send a properly authenticated request to the CoinPayments API, the following headers must be present:

• X-CoinPayments-Client
  • The integration client id.
• X-CoinPayments-Timestamp
  • The current timestamp in ISO format (excluding milliseconds and timezone).
• X-CoinPayments-Signature
  • A unique signature for each request, generated with the client secret.
  • See the Generate API Signature section for more information.

Prerequisites

• Create a CoinPayments account
• Log in to your CoinPayments account
• Verify your business account

1.) Navigate to the Integrations page

2.) Select "Add Integration"

3.) Select "API Integrations"

4.) Provide integration information

Define the integration name and provide your store URL.

5.) Review new integration information

Warning: The client secret is only displayed once. It is strongly recommended to save your credentials after they are shown to you.

If you lose your credentials, you can regenerate your client secret, invalidating all existing sessions.

6.) Optional: Configure Permissions

Limit the scope of authorized resources and operations this integration has access to.

7.) Optional: Define Allowed IPs

You can define a set of IP addresses that are allowed to make requests utilizing this integration. By default any IP address is allowed.

8.) Optional: Configure Webhooks

Specify the webhook endpoint and configure desired events to be received.

See the webhooks section for more information.

Prerequisites

• CoinPayments API Integration
• Integration Client ID
• Integration Client Secret

1.) Construct the unique request message

Concatenate the following data together to form the unique request message:

• \ufeff (Byte Order Mark)
• HTTP method
• URL
• Integration Client ID
• Timestamp (UTC ISO)
• Request payload (JSON)

2.) Hash the message using SHA-256, with the client secret as the key.

3.) Base64 encode the resulting SHA-256 hash.

4.) Use the Base64-encoded value in the X-CoinPayments-Signature header.

Example: Generate API Signature

The following example is written in Node.js.

import { createHmac } from 'node:crypto';
import axios from 'axios';

// Pull sensitive data from environment. 
const integration = {
    clientId: process.env.INTEGRATION_CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET
};

// Retrieve the current date in UTC ISO format (excluding milliseconds and timezone)
const isoDate = new Date().toISOString().split('.')[0]; // i.e. 2025-03-01T02:30:00

// Define request method, URL, and payload.
const request = {
    method:'POST',
    url: 'https://api.coinpayments.com/api/v1/merchant/wallets',
    data: {
        currencyId: 2,
          label: 'Online Shop Wallet',
          webhookUrl: 'https://api.my-store.com/webhooks/endpoint',
    }, // or null
    headers: {
        'X-CoinPayments-Client': integration.clientId,
        'X-CoinPayments-Timestamp': isoDate,
        'X-CoinPayments-Signature': '' // generated below
    }
}

// Convert payload to JSON string, if absent, an empty string ('').
const payloadMessage = request.data ? JSON.stringify(request.data) : '';

// Construct the unique request message
const message = `\ufeff${request.method}${request.url}${integration.clientId}${isoDate}${payloadMessage}`;

// Hash the message using SHA-256, digesting in Base64. 
const signature = createHmac('sha256', integration.clientSecret)
                    .update(message)
                    .digest('base64');

// Set request header.
request.headers['X-CoinPayments-Signature'] = signature;

// Send API request.
axios(request)
    .then((response) => console.log(response.data))
    .catch((err) => console.log(`Error code: ${err.status}`));

If you lose access to your integration credentials, you can regenerate the client secret.

Keep in mind that this will invalidate all existing sessions for this integration.

1.) Navigate to the integrations page

2.) Select the integration

3.) Reset the integration's client secret

4.) Copy and save the new client secret

---

Getting started with Postman is simple:

1. Clone our API collection.
2. Provide the clientId and clientSecret from your API integration.
3. Review route documentation and start interfacing with CoinPayments!

Currency identifiers are assigned internally by CoinPayments to each coin and token that the system supports.

currencyId fields are used commonly throughout the CoinPayments API. Relevant /currencies endpoints have been exposed to alow merchants to view the list of available cryptocurrencies within the system and evaluate their capabilities.

To enable interfacing with multiple tokens on the same blockchain, each token id will be the base coin id combined with the smart contract address.

For tokens, the currency id format is as follows: {coinId}:{smartContractAddress}

i.e. for ERC20 USDT on the Ethereum chain (id 4), the currency id would return 4:0xdac17f958d2ee523a2206206994597c13d831ec7

Retrieve the current conversion rates for supported cryptocurrencies.

Retrieve the current network fees for supported cryptocurrencies.

CoinPayments provides merchants with the flexibility to create and manage wallets either through the user-friendly dashboard or via API requests.

The Wallets API provides a set of endpoints that enable merchants to:

• Create new wallets and addresses for each coin supported by the platform.
• Initiate spend requests for withdrawals or currency conversions.
• Execute wallet consolidation via the Wallets Consolidation API.
• Retrieve wallet, address, and transaction statuses.

With this powerful functionality, merchants have extensive control and flexibility in managing their cryptocurrency wallets, catering to the specific needs of their business.

UI vs API Wallets

Wallets created on the CoinPayments dashboard cannot be accessed or managed through the API.

You will need to create a new wallet to utilize the Wallets API.

If you need to migrate from a UI wallet to an API wallet, you can sweep funds between the two wallets.

NOTE: Wallets can only be accessed/managed by the integration it was created by.

---

When creating a wallet via the CoinPayments API, you may set the usePermanentAddresses field to designate whether the wallet addresses should be temporary (default) or permanent.

For most operations, CoinPayments defaults to assigning a temporary address. When an address' designated function is complete (e.g., an invoice is marked as completed) or after a predefined inactivity timeout, the address is recycled back into the system pool. Any remaining balance on the address at the time of recycling is automatically credited to your account.

The primary benefit of using temporary addresses is the potential for reduced fees, facilitated by CoinPayments' internal system logic. However, if your application requires assigning a unique, persistent address to each customer, leveraging permanent addresses is the appropriate solution. Funds accumulated by permanent addresses can be swept (consolidated) as needed.

Permanent addresses are immediately available to receive funds upon creation. However, a one-time activation fee is incurred when initiating the first fund sweep operation or withdrawal from a specific permanent address. While this activation fee represents an initial cost, subsequent withdrawals or sweeps from activated permanent addresses are typically more economical for repeated use compared to temporary addresses.

UTXO (Unspent Transaction Output) addresses inherently facilitate fund accumulation. This characteristic enables potential reductions in network fees when withdrawing funds in bulk. CoinPayments refers to UTXO addresses created via the API as "permanent addresses".

---

• internalReceive - receiving funds from within the CoinPayments system;
• utxoExternalReceive - receiving UTXO funds from an external source;
• accountBasedExternalReceive - receiving funds from external account-based addresses;
• externalSpend - sending funds to an external address;
• internalSpend - sending funds from one CoinPayments user to another;
• sameUserSpend - sending funds from one wallet to another for the same CoinPayments user;
• sameUserReceive - receiving funds from one wallet to another for the same CoinPayments user;
• accountBasedExternalTokenReceive - receiving tokens from external account-based transfers;
• accountBasedTokenSpend - sending account-based tokens to external address;
• conversion - converting funds between user wallets;
• autoSweeping - funds swept automatically to an external wallet by the auto-sweeping feature;
• receiveTestFundsFromPool - receiving test funds;
• returnTestFundsToPool - returning test fund;
• unknown - transaction state unknown.

---

• created - initiated withdrawal, tx is not on the blockchain yet;
• pending - detected tx on the blockchain, tx awaiting required confirmations;
• processing - tx validation state is being processed;
• completed - tx has been put on chain, can be detected in the blockchain mempool (or an internal withdrawal is completed);
• expired - tx was not confirmed and has expired;
• failed - tx has failed;
• confirmedOnBlockchain - tx received all required confirmations on the blockchain, withdrawal/deposit is completed;
• pendingReceive - awaiting incoming deposit, tx is on chain, awaiting required confirmations;
• failedOnBlockchain - tx has not received required amount of confirmations;
• cancelled - tx has been cancelled;
• rejected - tx has been rejected by party;
• unknown - tx status unknown.

---

Merchants often leverage custom scripts for receiving customer payments, such as subscription renewals or account top-ups (e.g., funding a casino account). To enhance this process, you can embed deposit details (amount, currency, address) into a QR code. This method simplifies payment execution for customers and significantly reduces the likelihood of errors when transferring funds.

See this code example for QR code generation.

---

The Wallets Consolidation API allows merchants to consolidate funds from multiple permanent addresses into a wallet balance of the same currency.

Withdrawing from permanent addresses requires consolidating individual address balances into a wallet balance. This consolidation process incurs specific fees:

• Activation Fee: A one-time fee applied per address upon its initial consolidation.
• Transfer Fee: A per-address fee applied to each consolidation transaction.

Automatic Consolidation via Spend Request

This method leverages the spend request endpoint to initiate both a withdrawal and the required address consolidation automatically.

By providing only the wallet and desired amount, the user delegates address selection to the CoinPayments system. The platform algorithmically determines the most efficient combination of addresses to consolidate, considering the withdrawal amount, address balances, and activation statuses to optimize the transaction.

This approach streamlines withdrawals, especially when specific address preservation (i.e. permanent address strategic funds) is not a requirement.

Manual Consolidation

This method grants merchants direct control over address selection for consolidation using specific endpoints designed for either single- or multi-wallet consolidation tasks.

• createWalletConsolidationV2 to consolidate select addresses within a single source wallet.
• createWalletsConsolidationV2 to consolidate select addresses from multiple same-currency wallets into a target wallet.

You can preview the consolidation, including potential fees, with this request.

This approach offers granular control over address consolidation, but requires additional effort for identification and input.

IMPORTANT: Manual consolidation must always target a wallet designated for temporary addresses.

The manual consolidation reference is available on our extended documentation site.

CoinPayments exposes various endpoints within the Invoices API, enabling merchants to implement a crypto payment gateway on their platform to suit their specific needs. This allows customers to pay for goods and services in a wide selection of cryptocurrencies.

Primary use-cases within the Invoices API:

1. Create invoice links for payment collection.
2. Build custom white-label checkout solutions for your business.
3. Create "Buy Now" buttons for express customer checkout.

Let us consider a subscription-based business model. Every month you need to send out an invoice to your users with the upcoming payment, and ultimately the ability to collect said payment in crypto. In order to automate this flow, you may want to use the CoinPayments API. Here are the steps to achieve this functionality:

1. Create an invoice by making a request to POST /merchant/invoices
2. Send invoice payment link to client based on the API response. (invoice.link)
3. Check invoice status via configured webhooks, GET /merchant/invoices?q=${invoice.id}, or GET /invoice/:id/payment-currenciues/:currencyId/status

NOTE: In order for this request to work as expected, the merchant must exclude the payment object within the request. This allows the customer to enter their own contact details, initiating the payment and Payment Timeout when ready.

The generated CoinPayments invoice will display all relevant information to the customer:

• Merchant information
• Line item details and breakdown
• Invoice total and cryptocurrency
• Checkout link to complete the payment

By leveraging the CoinPayments API, you can allow buyers to purchase goods on your website under your own branding with cryptocurrency.

To accomplish this, review the following flow:

1. Merchant collects customer's email address, desired items, and calculates associated costs.
2. Customer clicks a "check out" button within your website, initiating the payment flow.
3. Create a payment link by making a request to POST /merchant/invoices

Make sure to include the payment object, populating refundEmail with the client's email address.

This is referenced to handle Overpayments and Underpayments.

4. Display the invoice.checkoutLink to the client to complete the payment in the allotted Payment Timeout.
5. Check invoice status via configured webhooks, GET /merchant/invoices?q=${invoice.id}, or GET /invoice/:id/payment-currenciues/:currencyId/status.

The generated payment page will display all relevant information to the customer:

• Merchant information
• Line item details and breakdown
• Invoice total, cryptocurrency, and conversion rate
• QR Code to complete the payment
• Payment Timeout in which payment must be made

See the code examples on how to change the QR code color and display.

Let us consider a case in which you run an online shop and want to accept cryptocurrency for your goods or services. To make the process quick and seamless for your customers, you can add a "Buy Now" button next to each item. Using the CoinPayments API, you can enable your customers to complete their purchase with just a few clicks. Here’s how the process works:

1. Generate "Buy Now" button by sending a request to POST /merchant/invoices/buy-now-button or alternatively, via the dashboard.
   • Specify the product/service details, webhook notifications, button styling, and more by referencing the route documentation.
   • Set the type to permanent.
2. Display the generated HTML from the API within your website, rendering the "Pay Using CoinPayments" button.

3. Customer wants to purchase merchant product/service immediately, so they click the adjacent "Pay with CoinPayments" button, initiating the payment flow.
4. Check invoice status via configured webhooks, GET /merchant/invoices, or GET /invoice/:id/payment-currenciues/:currencyId/status

Funds that are received by the merchant are deposited into the user's CoinPayments wallet balance by default. Funds within your balance can be withdrawn at any time.

You can configure additional ways to "settle" these payments by adjusting your Payment Settings on the dashboard.

The following settlement modes are available for payments received:

• To Balance - Received payments are stored in your CoinPayments wallet for later withdrawal at your leisure. This option allows you to automatically convert payments into another currency as well.
• To Address - Received payments are sent to the address or wallet ID you specify as soon as they are received and confirmed. This option allows you to automatically convert payments into another currency as well.
• Hourly to Address - Received payments are grouped together and sent hourly. The main benefit of this option is it will save you coin network fees.
• Nightly to Address - Received payments are grouped together and sent daily (at approx. midnight EST GMT-05:00). The main benefit of this option is it will save you coin network fees.
• Weekly to Address - Received payments are grouped together and sent every Sunday (at approx. midnight EST GMT-05:00). The main benefit of this option is it will save you coin network fees.

When the checkout/invoice payment flow is initiated, the exchange rate of the selected cryptocurrency will be held for the duration of the Payment Timeout (60 minutes).

Once the Payment Timeout has expired, the checkout screen will become locked and any pending payments will not be marked as completed for the associated transaction, resulting in an automatic refund.