Coinpayments API docs defines a standard, language-agnostic interface to CoinPayments API. The platform allows merchants to integrate the payment system into their own websites or applications, allowing 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 and responses, and how to handle errors. Overall, the API is designed to provide a simple and secure way for merchants to accept cryptocurrency payments from their customers. In these docs you'll find everything you need to leverage CoinPayments for your applications.

Also, while studying documentation, you can test it in Postman. For this, you can download API collection here. For information on authentication with the Postman collection, please, visit this section.

To create test transactions, you can use LTCT coins. To claim LTCT, just click on the "Get Free LTCT" button next to the corresponding coin balance.

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.

Some of the key features of the website include:

1. Support for multiple popular cryptocurrencies, allowing customers to pay with the digital currency of their choice.
2. Processing and managing various transaction types:
   • InternalReceive - receiving funds within the system;
   • UtxoExternalReceive - receiving funds from external UTXO transfers;
   • AccountBasedExternalReceive - receiving funds from external account-based transfers;
   • ExternalSpend - sending funds to the address that does not belong to CoinPayments;
   • 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's wallets;
   • AutoSweeping - funds swept automatically to an external wallet by the auto-sweeping feature configured by the user;
   • ReceiveTestFundsFromPool - give out funding for testing;
   • ReturnTestFundsToPool - return test fund.
3. Generate invoices and manually share them with buyers through a link or via email.
4. Callback Addresses feature allows merchant to receive payment without specifying the amount or time in advance.
5. Real-time updates using Webhooks. The API provides updates on the status of transactions, allowing merchants and customers to track the progress of their payments.
6. Advanced security measures to ensure that all transactions are safe and secure.

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 v1 API
• create invoice in PHP using CPS v2 API
• create invoice in C# using CPS v1 API
• create invoice in C# using CPS v2 API

If you’d rather skip sharing an invoice with the buyer and directly provide a payment address, check out this PHP example using the CPS v1 API. This example demonstrates how to generate an invoice with a cryptocurrency payment address all in one step, plus automatically create a QR code for seamless payment processing.

For more information on invoice white labeling see this section.

Learn how to create wallets with this PHP V1 API example.

Then see this example to learn how to send money between your wallets.

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.

With this C# V1 API example you can learn how to check the conversion rate for a specific fiat amount to crypto.

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 CoinPayment 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

This error occurs when an invalid clientId or clientSecret is used to generate API signature to authenticate requests. It may also occur if a clientId is valid but the integration is either deleted or the user's account does not exist. or an invalid or incorrect client secret is provided. In such cases, the API returns an "Unauthorized" error.

Insufficient Funds

This error can occur in different scenarios, such as during withdrawal to an external address or when converting a coin to another, whether to an internal or external address. It arises when the user's wallet does not have enough balance to cover the requested transaction amount.

Invalid Address

When sending a request to create a withdrawal or a conversion, if the provided address is not valid or formatted incorrectly, this error is triggered. Users should double-check the address they provided and ensure it follows the required format. here are 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 requested invoice, withdrawal, conversion involves an invalid or unsupported currency. It could be due to the currency not being listed or supported on the platform. Users can utilize the currencies API included in the documentation to list all supported currencies and verify if their intended currency is supported before initiating the transaction.

Bad request ( Input validation errors ):

This error occurs when there are issues with the validation of fields in the request's payload. For example, if a required field is not sent, or if the fields have invalid values or incorrect types. The API response for a validation error includes a description of the error and may provide details about the missing fields or the specific issues with the payload.

The API provides access to our platform's data and functionality, but in order to maintain the stability and performance of our services, rate limits have been implemented. Rate limits are set to prevent excessive use of the API and to ensure fair usage among all integrations. Currently, the rate limit is capped at a maximum of 70 requests per second.

CoinPayments API uses SHA-256 which is a way of authenticating an API request to ensure that it comes from a trusted source. In this scheme, the API server generates a unique signature for each request using the SHA-256 hashing algorithm.

Note: Currencies API, Rates API and Fees API endpoints do not require authorization.

Prerequisites

To Integrate Coin Payments API you need to obtain CLIENT ID and CLIENT SECRET. If you have already created your credentials, you may skip to next section.

First, you need to create an account.

Then log into your account.

Once you're logged into your account, click on Integrations 👇

API integrations 🏗

Add integration ➕

Give a name and a URL to your integration - more on the URL later.

Warning It is strongly recommended that you save your credentials after they are shown to you. Your credentials will only be displayed once, and if you lose them, you will not be able to access the API. Please take the time to save your credentials in a secure location so that you can use them in the future.

---

In order to properly sign an authenticated request for the CoinPayments v2 API, the following headers must be included:

• X-CoinPayments-Client
• X-CoinPayments-Timestamp
• X-CoinPayments-Signature

The following sections are instructions for properly populating these headers.

---

X-CoinPayments-Client

Populate this header with your clientId.

Example value cc7caaa431d54ad6accfd28b20170ee4

---

X-CoinPayments-Timestamp

Before we Populate this header with the current time as a UNIX timestamp, exclude the milliseconds epoch, example:

const date = new Date().toISOString().split(".")[0];

Example value: 2022-12-19T19:27:04

---

Construct the request queryString

To create an API signature, you first need to construct the query string which is made of the following attributes concatenated together

• method
• url
• clientId
• date

Example ( Javascript )

const queryString = `\ufeff${method}${url}${clientId}${date}${JSON.stringify(requestPayload)}`;

For requests with no request body, replace last attribute by an empty string: Example ( Javascript )

const queryString = `ufeff${method}${url}${clientId}${date}${''}`;

---

X-CoinPayments-Signature

Next step is to use your clientSecret to generate the signature using SHA-256 encryption algorithm as follows:

const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

Example value: oW7d1ktvK7R6741oACgVR3bysGTPY8tqren0WTmmEk0=

---

Here is a complete example of how to generate an API signature for making a call to the create wallet API:

const clientId = 'd0ccc52b8204460783d375e278082de2';
const clientSecret = 'WYEB+hN+89waO76QeO9T7IIqhdo/60GHrdYu2vEa7Tg=';
const url = `https://api.coinpayments.com/api/v1/merchant/wallets`;
const method = 'POST';
const date = new Date().toISOString().split('.')[0];

const createWalletDto = {
  currencyId: 2,
  label: 'Online Shop Wallet',
  webhookUrl: 'https://mysite.com/api/v1/payment/notification',
};

const queryString = `\ufeff${method}${url}${clientId}${date}${JSON.stringify(createWalletDto)}`;


const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

const headers = {
  'X-CoinPayments-Client': clientId,
  'X-CoinPayments-Timestamp': date,
  'X-CoinPayments-Signature': signature,
};


/** Make API call using axios ( you may choose any http client ) */
const axiosoptions = {
  url,
  headers,
  method,
  data: createWalletDto,
};

const response = await this.httpsService.request(options).toPromise();
console.log(response);

---

When setting up authentication with Postman to test out our API collection, follow these steps:

1. Set up environment variables:

• Use https://api.coinpayments.com/api/ as baseUrl.
• Provide your clientID and clientSecret from your API integration.

2. Provide the following script in the collection Pre-request Script section:

---

const crypto = require('crypto-js')
const clientId = pm.environment.get('clientId')
const clientSecret = pm.environment.get('clientSecret')

const date = new Date().toISOString().split('.')[0];

const queryString = `\ufeff${pm.request.method}${pm.variables.replaceIn(pm.request.url.toString())}${clientId}${date}${pm.request.body}`;
const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

pm.request.headers.add({
    key: 'X-CoinPayments-Client',
    value: clientId
})

pm.request.headers.add({
    key: 'X-CoinPayments-Timestamp',
    value: date
})

pm.request.headers.add({
    key: 'X-CoinPayments-Signature',
    value: signature
})

---

API for managing clients access rights

In order to perform most API requests regarding payment/wallet management, the merchant has to provide a currency ID in the request. CoinPayments exposes currencies API endpoints allowing merchants to view the list of available cryptocurrencies in the system and learn about their details and capabilities.

Each currency supported by CoinPayments has a specific ID assigned to it. Besides, CoinPayments supports both native coins and tokens. In order to allow managing tokens of the same blockchain, CoinPayments API contains information on both - ID of the coin blockchain, where token belongs, and the smart contract address of the token. This information is returned in the format 'coinID:smartContract'. For example, if ID of ETH is "4", then for ERC20 USDT it would be "4:0xdac17f958d2ee523a2206206994597c13d831ec7".

Currency IDs are used for creating and listing merchant wallets. When creating a wallet, if only native currency ID is specified, the wallet is created for the same native currency. In case a wallet for the token is required, merchant must additionally indicate the token contract address when creating a wallet. See Create Wallet.

Also, currency IDs and contract addresses are used when creating transactions from a merchant wallet. For example, the body of the spend request specifically indicates the "toCurrency" ID and "from" and "to" contract addresses. This allows CoinPayments to indicate whether the said transaction is a regular withdrawal of funds or a transaction that additionally requires conversion. See Spend Request.

Below, you will find the detailed information on currency-related endpoints and their field values.

API for rates supported by CoinPayments

API for current network fee for currencies

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.

---

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 rus 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 main UI 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 must consolidate addresses balances at the UI wallet balance. For this each new address created within the API wallet 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 UI wallet balance. However, the network fee for further withdrawal of the consolidated funds is charged everytime 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 buyer by incorporating payment details like payment amount, currency and payment 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.

---

Unlike wallets and addresses created via UI, wallets and addresses created via API can send webhook notifications to the URL specified by the merchant. The URL for receiving webhook notifications is specified at wallet/address creation or update.

Authenticate Webhooks from CoinPayments to Your Server

CoinPayments will send webhooks from one of these IPs:

hook1.coinpayments.com - 23.183.244.249

hook2.coinpayments.com - 23.183.244.250

All webhook messages from CoinPayments contain the same headers as used by merchants to sign requests to CoinPayments API:

const headers = {
  'X-CoinPayments-Client': clientId,
  'X-CoinPayments-Timestamp': date,
  'X-CoinPayments-Signature': signature,
};

By verifying the signature with the help of the private key, merchant can make sure that the received webhook is produced by CoinPayments server.

Webhook Types

The list of wallet/address transactions that support webhook notifications includes:

• InternalReceive - receiving funds within the system;
• UtxoExternalReceive - receiving funds from external UTXO transfers;
• AccountBasedExternalReceive - receiving funds from external account-based transfers;
• InternalSpend - sending funds to the address that belongs to CoinPayments;
• ExternalSpend - sending funds to the address that does not belong to CoinPayments;
• 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.

Below is an example of the webhook notification thrown when an external withdrawal is made from a wallet:

{
  "walletId": "5ff25090-4f3a-4cc4-a187-59fce3f4e501",
  "address": "miG63NqftkbxNYzHBkRQiZtdaE8xFsRSkr",
  "transactionId": "407ee3f9-4d8d-4ebe-8b82-39704906f931",
  "txHash": "c0581829ad6ccb1ba759799c00880917d16868aeba326781a4168fe32f961bdd",
  "spendRequestId": "189466f2-8c29-4b8e-abe3-86eb3de79e2b",
  "transactionType": "ExternalSpend",
  "amount": "0.15019097",
  "symbol": "LTCT",
  "coinPaymentsFee": "0",
  "coinPaymentsFeeSymbol": "LTCT",
  "blockchainFee": "0.000013",
  "blockchainFeeSymbol": "LTCT",
  "totalAmount": "0.15020397",
  "totalAmountSymbol": "LTCT",
  "nativeAmount": "10.03",
  "coinPaymentsFeeNativeAmount": "0",
  "blockchainFeeNativeAmount": "0",
  "totalNativeAmount": "10.03",
  "nativeSymbol": "USD",
  "confirmations": 3,
  "requiredConfirmations": 3
}

Also, below is the description of the typical wallet transaction webhook payload.

---