Skip to main content

API and endpoint description

Updated

NOWPayments API Documentation

All methods in the API are divided into two types: GET and POST. The main frequently used API requests are listed here; there are more of them in the document, and all of them have descriptions.

  • GET request method: Requests data from our system.
  • POST request method: Sends data to us so that we can process it and return some kind of result. The callback sent from our side is always POST.

Parameters in queries are also divided into two types:

  • Required (mandatory to fill in).
  • Optional (which can be left blank).

Authorization Endpoints

POST /auth

Category: Authorization
Description: Obtains a JWT token for API authentication. Required for payout requests.
Endpoint:
https://api.nowpayments.io/v1/auth

Headers:

  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 email  String Yes  User's email (case-sensitive)
 password  String Yes  User's password (case-sensitive)

 

Response:

  • token (String) - JWT token valid for 5 minutes

Notes:

  • Token expires after 5 minutes
  • Email/password are case-sensitive

Payment Endpoints

GET /currencies

Category: Payment
Description: Retrieves list of available cryptocurrencies
Endpoints:

  1. Basic list:
    https://api.nowpayments.io/v1/currencies
  2. With fixed rate info:
    https://api.nowpayments.io/v1/currencies?fixed_rate=true
  3. Detailed info:
    https://api.nowpayments.io/v1/full-currencies
  4. Merchant-specific:
    https://api.nowpayments.io/v1/merchant/coins

Headers:

  • x-api-key (Required)

Query Parameters:

Parameter Type Required Description
 fixed_rate  Boolean No  Shows min/max amounts for fixed rate

GET /min-amount

Category: Payment
Description: Gets minimum payment amount for currency pair
Endpoint:
https://api.nowpayments.io/v1/min-amount

Query Parameters:

Parameter Type Required Description
 currency_from  String Yes  Source currency (e.g. "eth")
 currency_to  String Yes  Target currency (e.g. "trx")
 fiat_equivalent  String No  Returns amount in specified fiat
 is_fixed_rate  Boolean No  For fixed rate calculations
 is_fee_paid_by_user  Boolean No  When user pays network fees

 

Response Fields:

  • min_amount - Minimum payment amount
  • fiat_equivalent - Fiat equivalent (if requested)

POST /invoice

Category: Payment
Description: Creates payment invoice
Endpoint:
https://api.nowpayments.io/v1/invoice

Headers:

  • x-api-key (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 price_amount  Number Yes  Amount in fiat
 price_currency  String Yes  Fiat currency (e.g. "usd")
 pay_currency  String No  Crypto currency to pay with
 ipn_callback_url  String No  Callback URL
 order_id  String No  Merchant order ID
 is_fixed_rate  Boolean No  Lock exchange rate

NOWPayments API Documentation

All methods in the API are divided into two types: GET and POST. The main frequently used API requests are listed here; there are more of them in the document, and all of them have descriptions.

  • GET request method: Requests data from our system
  • POST request method: Sends data for processing
  • Parameters: Required (must be included) | Optional (can be omitted)

API endpoints are categorized as:

  • Authorization: Authentication and token management
  • Payment: Payment processing and transactions
  • Payout: Withdrawals and funds transfer
  • Custody: Account balance and conversions

Authorization Endpoints

POST /auth

Category: Authorization
Description: Obtains JWT token for API authentication (valid for 5 minutes)
Endpoint: https://api.nowpayments.io/v1/auth
Headers:

  • Content-Type: application/json (Required)

Request Parameters (JSON Body)

Parameter Type Required Description
 email  String Yes  Account email (case-sensitive)
 password  String Yes  Account password (case-sensitive)

Response:

  • token (String) - JWT token for authenticated requests

Payment Endpoints

GET /currencies

Category: Payment
Description: Retrieves available cryptocurrencies
Endpoints:

  1. https://api.nowpayments.io/v1/currencies
  2. https://api.nowpayments.io/v1/currencies?fixed_rate=true
  3. https://api.nowpayments.io/v1/full-currencies
  4. https://api.nowpayments.io/v1/merchant/coins

Headers:

  • x-api-key (Required)

Query Parameters:

Parameter Type Required Description
 fixed_rate  Boolean No  Include min/max amounts for fixed-rate payments

GET /min-amount

Category: Payment
Description: Gets minimum payment amount for currency pair
Endpoint: https://api.nowpayments.io/v1/min-amount
Headers:

  • x-api-key (Required)

Query Parameters:

Parameter Type Required Description
 currency_from  String Yes  Source currency (e.g. "eth")
 currency_to  String Yes  Target currency (e.g. "trx")
 fiat_equivalent  String No  Return amount in specified fiat currency
 is_fixed_rate  Boolean No  Calculate for fixed-rate payments
 is_fee_paid_by_user  Boolean No  Calculate when user pays fees

Response:

  • min_amount (Float) - Minimum payment amount
  • fiat_equivalent (Float) - Fiat equivalent (if requested)

POST /invoice

Category: Payment
Description: Creates payment invoice
Endpoint: https://api.nowpayments.io/v1/invoice
Headers:

  • x-api-key (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 price_amount  String Yes  Amount in fiat currency
 price_currency  String Yes  Fiat currency code (e.g. "usd")
 pay_currency  String No  Cryptocurrency for payment
 ipn_callback_url  String No  Instant Payment Notification URL
 order_id  String No  Merchant order ID
 order_description  String No  Order description
 success_url  String No  Redirect after successful payment
 cancel_url  String No  Redirect after failed payment
 is_fixed_rate  Boolean No  Lock current rate (true/false)
 is_fee_paid_by_user  Boolean No  User pays fees (true/false)

Response:

  • invoice_url (String) - Payment URL for customers
  • id (String) - Invoice ID

POST /payment

Category: Payment
Description: Creates direct payment
Endpoint: https://api.nowpayments.io/v1/payment
Headers:

  • x-api-key (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 price_amount  String Yes  Amount in fiat currency
 price_currency  String Yes  Fiat currency code (e.g. "usd")
 pay_currency  String No  Cryptocurrency for payment
 ipn_callback_url  String No  Instant Payment Notification URL
 order_id  String No  Merchant order ID
 order_description  String No  Order description
 is_fixed_rate  Boolean No  Lock current rate (true/false)
 is_fee_paid_by_user  Boolean No  User pays fees (true/false)

Response:

  • payment_id (String) - Unique payment identifier
  • pay_address (String) - Deposit address for customer

POST /payment/:id/update-merchant-estimate

Category: Payment
Description: Gets/updates payment estimate
Endpoint: https://api.nowpayments.io/v1/payment/:id/update-merchant-estimate
Headers:

  • x-api-key (Required)
  • Content-Type: application/json (Required)

Path Parameters:

Parameter Type Required Description
 id  String Yes  Payment ID

 

Response:

  • pay_amount (Float) - Updated payment amount
  • expiration_estimate_date (String) - Estimate validity period

GET /estimate

Category: Payment
Description: Estimates cryptocurrency price for fiat amount
Endpoint: https://api.nowpayments.io/v1/estimate
Headers:

  • x-api-key (Required)

Query Parameters:

Parameter Type Required Description
 amount  Number  Yes  Fiat amount to convert
 currency_from  String  Yes  Source fiat currency
 currency_to  String  Yes  Target cryptocurrency

GET /payment/:payment_id

Category: Payment
Description: Gets payment status
Endpoint: https://api.nowpayments.io/v1/payment/:payment_id
Headers:

  • x-api-key (Required)

Path Parameters:

Parameter Type Required Description
 payment_id  String Yes  Payment ID to check

Status Values:

  • waiting - Awaiting payment
  • confirming - Blockchain processing
  • confirmed - Blockchain confirmed
  • finished - Payment completed
  • failed - Payment failed
  • expired - Payment window expired

GET /payment/

Category: Payment
Description: Lists all payments
Endpoint: https://api.nowpayments.io/v1/payment/
Headers:

  • Authorization: Bearer {token} (Required)
  • x-api-key (Required)

Query Parameters:

Parameter

Type

Required

Description
 limit  Number No  Results per page (1-500)
 page  Number No  Page number
 sortBy  String No  Field to sort by
 orderBy  String No  Sort direction (asc/desc)
 dateFrom  Date No  Filter start date
 dateTo  Date No  Filter end date
 invoiceid  String No  Filter by invoice ID

Payout Endpoints

GET /balance

Category: Payout
Description: Retrieves account balances
Endpoint: https://api.nowpayments.io/v1/balance
Headers:

  • x-api-key (Required)

Response:

json
 
{
  "btc": {
    "amount": 0.5,
    "pendingAmount": 0.1
  }
}

POST /payout/validate-address

Category: Payout
Description: Validates payout address
Endpoint: https://api.nowpayments.io/v1/payout/validate-address
Headers:

  • x-api-key (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 address  String Yes  Cryptocurrency address
 currency  String Yes  Currency ticker
 extra_id  String No  Memo/destination tag

POST /payout

Category: Payout
Description: Creates cryptocurrency payout
Endpoint: https://api.nowpayments.io/v1/payout
Headers:

  • Authorization: Bearer {token} (Required)
  • x-api-key (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

json
 
{
  "withdrawals": [
    {
      "address": "recipient_address",
      "currency": "btc",
      "amount": 0.5,
      "extra_id": null
    }
  ]
}

Parameters:

Parameter Type Required Description
 address  String Yes  Recipient address
 currency  String Yes  Cryptocurrency
 amount  Number Yes  Payout amount
 extra_id  String No  Memo/destination tag
 ipn_callback_url  String No  Callback url
 fiat_amount  Number No  Fiat equivalent amount
 fiat_currency  String No  Fiat currency for amount
 execute_at  Date

No

  Date and time when the payout will be executed
 interval  String
 Uppercase

No

  Desired payout interval - ONETIME only supported

Statuses: NEW, CREATING, WAITING, PROCESSING, FINISHED, REJECTED, REJECTED_NOT_CHECKED

Scheduled payouts flow

 

This flow allows you to execute payouts at a specific time in the future. This feature is perfect for businesses that need to automate payments but require more control over the timing. Instead of initiating payouts immediately, you can set them to be processed at a later date, providing additional flexibility and efficiency.

 

How it works:

 

  • specify the exact date and time when the payout will be executed, in the format: YYYY-MM-DDTHH:mm:ss.sssZ. with the execute_at param (required for this flow). For example: "2026-02-29T10:35:00.000Z"

     

  • specify the desired interval: currently, only ONETIME is supported. This indicates that the payout is a one-time event.

     

 

These parameters should be provided before the payout details like amount, currency, and address in the request payload (POST Create payout).

 

Key Features:

 

  • E-mail notification: you will be notified 24 hours before the scheduled payout via your registration email.

     

  • Canceling a Payout: you can cancel a scheduled payout via the POST /v1/payout/w_id/cancel endpoint. The canceled payout will be marked with the status cancelled.

     

  • Information in Dashboard: In the personal account dashboard, you will see the new parameter Scheduled Time for such payouts in the payout card.

POST /payout/w_id/cancel

Category: Payout
Description: Cancel scheduled payout
Endpoint: https://api.nowpayments.io/v1/payout/w_id/cancel
Headers:

  • Content-Type: application/json (Required)

Params:

 

  • w_id - the unique identifier of the planned payout you want to cancel. This should be the ID of the individual payout, not the batch ID.
Parameter Type Required Description
 w_id   String Yes  Payout ID

POST /payout/:batch-withdrawal-id/verify

Category: Payout
Description: Verifies payout with 2FA code
Endpoint: https://api.nowpayments.io/v1/payout/:batch-withdrawal-id/verify
Headers:

  • Authorization: Bearer {token} (Required)
  • x-api-key (Required)
  • Content-Type: application/json (Required)

Path Parameters:

Parameter Type Required Description
 batch-withdrawal-id  String Yes  Payout batch ID

 

Request Parameters (JSON Body):

Parameter Type Required Description
verification_code  String Yes  2FA verification code

GET /payout/fee

Category: Payout
Description: Estimates network fee for payout
Endpoint: https://api.nowpayments.io/v1/payout/fee
Headers:

  • x-api-key (Required)

Query Parameters:

Parameter Type Required Description
currency String Yes Cryptocurrency ticker
amount Number Yes Payout amount

Custody Endpoints

GET /conversion

Category: Custody
Description: Lists currency conversions
Endpoint: https://api.nowpayments.io/v1/conversion
Headers:

  • Authorization: Bearer {token} (Required)

Query Parameters:

Parameter Type Required Description
 id  Number/Array No  Filter by conversion ID
 status  String/Array No  Filter by status
 from_currency  String No  Filter by source currency
 to_currency  String No  Filter by target currency
 created_at_from  Date No  Filter start date
 created_at_to  Date No  Filter end date
 limit  Number No  Results limit (default: 10)
 Offset  Number No  Pagination offset
 Order  String No  Sort order (ASC/DESC)

POST /sub-partner/write-off

Category: Custody
Description: Transfers funds from sub-account to master account
Endpoint: https://api.nowpayments.io/v1/sub-partner/write-off
Headers:

  • Authorization: Bearer {token} (Required)
  • Content-Type: application/json (Required)

Request Parameters (JSON Body):

Parameter Type Required Description
 currency  String Yes  Currency for transfer
 amountsub_partner_id  Number Yes  Amount to transfer
 sub_partner_id  String Yes  Sub-account ID

Statuses: CREATED, WAITING, FINISHED, REJECTED

 You can find more details and parameters for endpoints in our official API Documentation here

Related articles

Powered by Zendesk