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

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

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 UI or via API calls. Due to security reasons, wallets created via UI cannot be managed via API. However, all wallets created via API are available through UI with the full functionality scope. Hence, in case merchant requires their funds from the wallet that was originally created via UI to be accessible via API, they need to sweep funds from the "UI wallet" to the "API wallet".

Since merchants may have several API clients activated, it is important to note that wallets created under one API client cannot be controlled by a different API client.

The Wallets API provides a set of endpoints that enable merchants to create new wallets with the coins supported by the platform, as well as initiate withdrawal requests from their wallets to any external or internal address of their choosing. With this powerful functionality, merchants have extensive control and flexibility in managing their cryptocurrency wallets to cater to their specific business needs.

Note: When sending funds to an address, make sure that the address you are sending to matches the token/coin that you credit to the address. Otherwise, this may lead to the funds being stuck in the network or even lost.

---

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

---

Addresses created via CoinPayments API are used as commercial addresses for commercial funds, e.g. gambler casino accounts. Hence, merchants require flexibility when accumulating and sweeping funds from such commercial addresses.

UTXO addresses, by their nature, allow for accumulation of funds and, hence, reduction of network fees when withdrawing funds in bulk from such addresses. Thus, it is possible to assign UTXO addresses to the merchant (and merchant can assign specific address to a specific customer) for permanent use without any considerable loss in service fees when managing funds. As a result, CoinPayments refers to UTXO addresses created via API as permanent addresses.

Account-based addresses created via CoinPayments API may be either temporary or permanent depending on the flag set up by the merchant when creating a new account-based address.

CoinPayments randomly emits temporary account-based address to a merchant so that the merchant could obtain a commercial deposit from a customer. The address stays in merchant's use for a certain period of time set up by the CoinPayments admins. When the time period expires, the address returns to the pool of CoinPayments addresses. This time period is renewed in case the address is topped up again before the set time period runs out. If the address returns to the pool, the funds are automatically assigned to the corresponding merchant API wallet within which the address had been emitted. Consolidation of funds from addresses at the main wallet balance is CoinPayments responsibility in this design and allows for reduction in fees when sweeping wallet balance elsewhere. Nevertheless, some merchants might find it uncomfortable that addresses cannot be assigned permanently to specific customers. Hence, customer must always check for the correct address before sending funds to the merchant.

The merchant can decide to use permanent account-based addresses if it is important to manage funds/balances deposited by their customers individually. For that, when creating a commercial wallet via API, merchant must enable the usePermanentAddresses flag. Thus, all the addresses created within such wallet will be permanent. This will allow merchant to assign specific addresses to specific clients perpetually. Such design allows for better customer experience. Also, merchant can manage themselves when to sweep funds from addresses to the wallet balance and further. Address balance is always swept in full to reduce the amount of cases when a small amount of funds is stuck on the address because the fee for withdrawal equals or higher than the withdrawn amount.

The tradeoff of the permanent address vs. temporary address design is fees. In order to be able to use the funds from permanent addresses, merchant first must consolidate addresses balances at some wallet balance without permanent addresses (either Primary UI balance of the currency or a wallet with temporary addresses). For this each new address created within the API wallet with permanent addresses must be activated.

The activation fee is charged only once when the first withdrawal from the address takes place and the funds are swept from the address to the wallet balance. However, the network fee for further withdrawal of the consolidated funds is charged every time funds are withdrawn from the wallet. Although address activation fees lead to larger expenses at the first sweep, each repetitive withdrawal of consolidated funds from the wallet is still way cheaper compared to regular withdrawal from an account-based address.

---

A common case for merchants is to use wallets and addresses created via API for receiving payments from their customers, e.g. top-up a subscription or casino account. A merchant can simplify the payment process for the customer by incorporating deposit details like deposit amount, currency and deposit address into a QR code. This will decrease the possibility of an error when sending funds.

For the QR code script example check description of the Payment Flow for Integrated Checkout with White Labeling in the Invoices API.

---

The Consolidation API allows merchants to consolidate funds from the permanent account-based addresses to a wallet balance (either UI Primary Balance or any API wallet of the same currency) before sweeping them elsewhere.

When using permanent account-based addresses, in order to withdraw funds from them, the user must first consolidate addresses balances at a wallet balance. Consolidation process involves payment of the activation fee if the address that is consolidated has not been activated yet, and a transfer fee for each consolidated address. The activation fee is paid only during the first consolidation. Further consolidations entail only transfer fees per consolidated address.

There are two consolidation options:

• Automatic option via creating a Spend Request for a withdrawal of funds from an API wallet. In this case user creates a simple withdrawal of funds from the wallet of interest via the sendSpendRequest endpoint and defers the decision on which addresses to consolidate to CoinPayments. CoinPayments defines the most optimal combination of addresses based on the amount that the user wants to withdraw from the wallet, the current balances of the addresses in the wallet and the fact whether addresses are already activated or not.

This approach allows users to save time on discovering the most beneficial solution for each particular withdrawal especially if user does not care about which addresses to sweep and which to use as a storage.

• Manual consolidation where the user explicitly states addresses to be consolidated. For more information on manual consolidation see our Extended API Documentation.

CoinPayments exposes invoices API endpoints allowing merchants to implement a payment gateway on their platform, and let buyers pay for goods and services in a wide selection of cryptocurrencies.

With CoinPayments invoices API you may:

1. Create invoice links for payment collection.
2. Build custom white label checkout solutions for your business.
3. Create buy-now buttons for quick buyers' checkout. CoinPayment’s invoices API is built around “invoice” entity. In other words, under the hood it generates an invoice with all the buyer’s and merchant’s data plus information on the product/service. Thus, merchants will be flexible in managing payments with the help of this data via a set of available endpoints.

Below you will find information on how payment flow is organized for each of the above-mentioned approaches.

Let us consider a subscription use case, where you have a platform that provides services with a subscription payment model. Every month you need to send out invoices to your users with the reminder to pay for the subscription and ability to collect this payment in crypto. In order to automate this flow, you may want to use CoinPayments API. Here are the steps that should take place in order for a payment to occur:

1. Merchant adds details on services for which invoice is issued, indicates user’s details like name, payment address and email, if provided.
2. With the help of createInvoice endpoint merchant generates an invoice entity with the data from step 1.
3. As a response to the createInvoice endpoint, merchant receives:

• an invoice Id to further check invoice status
• a link to the invoice document with the active payment button that would lead user to payment checkout.

Note: In order this request could work properly, merchant must make sure to eliminate the following attribute from the request:

   "payment": {
     "paymentCurrency": "4:0xdac17f958d2ee523a2206206994597c13d831ec7"
     "refundEmail": "jane_doe@hotmail.com"
   }

Providing the 'refundEmail' and 'paymentCurrency' will initiate the White Labeling flow disclosed below. Leaving 'payment' attribute empty will cause an error.

4. Invoice is added to merchant's account transaction history where merchant will be able to track payment status.
5. Merchant sends out the link to the invoice to the buyer.
6. Buyer enters their email for potential refunds, selects the currency for payment.
7. The buyer is presented with a payment address, total amount of cryptocurrency to-be-deposited, and a timer within which the transaction has to be completed.
8. At the same time currency of payment is reflected in the transaction details of the payment in the merchant's transaction history.
9. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending invoice payment notifications for each status change thereof (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

Let us consider a case where you have an online shop and you want to accept payment for goods in cryptocurrency. With CoinPayments API you will be able to allow buyers to request goods and pay with the cryptocurrency all at your website and under your own branding. Here are the steps that should take place in order payment could occur:

1. Buyer selects product/service on the merchant’s site and adds them to the shopping cart. At the checkout, buyer indicates their details like name, payment address and email and clicks "Pay".
2. By clicking "Pay", buyer launches the payment flow. In this flow, buyer's email provided when creating the order, is recorded as the 'RefundEmail' in the 'createInvoice' request for possible refunds in case of over- and underpayment.

   {
     ...
     "Payment": {
    "RefundEmail": "jane_doe@hotmail.com"
     }
   }
   

At the same time, the 'createInvoice' endpoint generates an invoice entity including:

• 'invoiceId' to get payment address and check payment status
• list of available currencies for payment with currency description, payment amount and fees
• payment expiration timestamp.

3. If merchant wants to allow buyer to select currency at checkout, payment address is obtained with the help of 'getPaymentAddressByCurrency' endpoint, once buyer chooses the currency for payment. If merchant's website has preset currency for all goods and services, the same endpoint must be triggered at step 2., once buyer clicks "Pay". As a result, buyer is presented with the following data:

• a currency id
• a payment address
• total amount of the selected cryptocurrency to be deposited
• timer for completing the transaction.

3.a. A merchant can combine steps 2 and 3 into one, i.e. create an invoice for the shopping cart content already with the payment in the specific cryptocurrency. For this, when creating invoice, merchant should provide id of the 'PaymentCurrency' in the 'Payment' entity of the 'CreateInvoice' request:

{
  ...
  "Payment": {
    "RefundEmail": "jane_doe@hotmail.com",
    "PaymentCurrency": "4:0xdac17f958d2ee523a2206206994597c13d831ec7"
    }
  }

The indication of the cryptocurrency id will trigger creation of the invoice together with payment and HotWallet (address for buyer). In the createInvoice response the merchant will receive a link to the CoinPayments checkout app:

{
    "invoices": [
        {
            ...
            "checkoutLink": "https://checkout.coinpayments.com/checkout/?invoice-id=56284ebf-8daf-4eed-a3a4-00a3ba255788",
    ...
    }
  ]
}

By providing the link to the buyer, she will get directly to the checkout page with the payment address, QR code and timer for payment.

4. After that merchant can check the status of the payment with the help of getPaymentStatus endpoint that includes:

• status of payment
• how much was detected and confirmed on blockchain
• how much was detected but not confirmed yet.

5. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending payment notifications for each status change (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

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>

---

Let us consider another case for an online shop where you want to accept payment for goods in cryptocurrency and want to allow your buyers to make quick purchases by clicking on the Buy-Now button next to the good or service you offer. With CoinPayments API you will be able to allow buyers to request goods and pay with the cryptocurrency in a matter of a few clicks. Here are the steps that should take place in order payment could occur:

1. Buyer detects product/service on the merchant’s site and wants to order them immediately, so they click on the "Pay with CoinPayments" button next to the product/service.
2. By clicking "Pay with CoinPayments", buyer launches the payment flow. As a first step of the flow, buyer is requested to provide their email. The email is recorded as the 'RefundEmail' in the creteInvoice request for possible refunds in case of over- and underpayment. At the same time, the createInvoice endpoint generates an invoice entity including:

• invoiceId to get payment address and check payment status
• list of available currencies for payment with currency description, payment amount and fees
• payment expiration timestamp.

3. If merchant wants to allow buyer to select currency at checkout, payment address is obtained with the help of getPaymentAddressByCurrency endpoint, once buyer chooses the currency for payment. If merchant's website has preset currency for all goods and services, the same endpoint must be triggered once buyer clicks "Pay". As a result, buyer is presented with a payment address, total amount of the selected cryptocurrency to be deposited, and a timer within which the transaction has to be completed.
4. After that merchant can check the status of the payment with the help of 'getPaymentStatus' endpoint that includes:

• status of payment
• how much was detected and confirmed on blockchain
• how much was detected but not confirmed yet.

5. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending payment notifications for each status change (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

Funds that merchants receive via payments are primarily deposited to the CoinPayments system balance. From there, CoinPayments conducts payouts to the merchant's balance. CoinPayments UI provides the merchant with a possibility to set up mode and frequency for paying out funds from CoinPayments balance to the merchant's own balance. The settings are set up by currency.

Below, you will find the detailed information on each of the invoices endpoints and their field values. Endpoints are the same for both described use-cases with the slight difference in utilizing certain fields in schemas. All such differences will be outlined explicitly.