NOWPayments API

{
  "service_type": "crypto_app",
  "base_url": "https://api.nowpayments.io",
  "auth_method": "api_key_header",
  "auth_config": {
    "header_name": "x-api-key",
    "jwt_required_for": "specific endpoints and advanced operations"
  },
  "endpoints": [
    {"path": "/v1/status", "method": "GET", "purpose": "check API status"},
    {"path": "/v1/currencies", "method": "GET", "purpose": "list supported cryptocurrencies"},
    {"path": "/v1/merchant/coins", "method": "GET", "purpose": "list merchant accepted coins"},
    {"path": "/v1/estimate", "method": "GET", "purpose": "estimate crypto amount for currency pair"},
    {"path": "/v1/min-amount", "method": "GET", "purpose": "get minimum payment amount"},
    {"path": "/v1/payment", "method": "POST", "purpose": "create direct crypto payment"},
    {"path": "/v1/invoice", "method": "POST", "purpose": "create hosted invoice"},
    {"path": "/v1/payment/{payment_id}", "method": "GET", "purpose": "get payment status"},
    {"path": "/v1/payment/{payment_id}", "method": "PUT", "purpose": "update payment"},
    {"path": "/v1/payout", "method": "POST", "purpose": "create single payout"},
    {"path": "/v1/payout/batch", "method": "POST", "purpose": "create batch payout"},
    {"path": "/v1/payout/validate-address", "method": "POST", "purpose": "validate payout address"},
    {"path": "/v1/payout/fee", "method": "GET", "purpose": "estimate payout fee"},
    {"path": "/v1/sub-partner", "method": "POST", "purpose": "create sub-partner account"},
    {"path": "/v1/sub-partner/balance/{id}", "method": "GET", "purpose": "get sub-partner balance"},
    {"path": "/v1/balance", "method": "GET", "purpose": "get account balances"},
    {"path": "/v1/currencies", "method": "GET", "purpose": "list supported currencies"}
  ],
  "pricing_model": {
    "type": "per_transaction",
    "details": {
      "gateway_fee": "0.5% per transaction",
      "fixed_rate_fee": "0.5% (locked rate for 10 minutes)",
      "floating_rate_fee": "0.5% (market rate at transaction time)",
      "mass_payouts_fee": "0.25% per payout",
      "zero_fee_payouts": "0% for ChangeNOW wallet payouts",
      "notes": "Fees may vary; see https://nowpayments.io/pricing for current rates"
    }
  },
  "rate_limits": {
    "rpm": 60,
    "notes": "Rate limits are not explicitly documented; typical values apply. Contact support for high-volume usage."
  },
  "capabilities": [
    "crypto_payments",
    "hosted_invoices",
    "payment_links",
    "direct_payments",
    "fixed_rate",
    "floating_rate",
    "mass_payouts",
    "recurring_payments",
    "donations",
    "ai_integrations"
  ],
  "crypto_specifics": {
    "supported_chains": [
      "ethereum",
      "bitcoin",
      "binance_smart_chain",
      "tron",
      "solana",
      "polygon",
      "avalanche",
      "litecoin",
      "dogecoin",
      "ripple",
      "cosmos",
      "near",
      "polkadot",
      "arbitrum",
      "optimism"
    ],
    "token_count": 300,
    "has_websocket": false,
    "has_orderbook": false,
    "fee_structure": "percentage_per_transaction",
    "security_features": [
      "api_key_authentication",
      "jwt_authentication",
      "ipn_callback_verification",
      "address_whitelisting",
      "withdrawal_whitelist"
    ],
    "payment_flow": {
      "fixed_rate": "exchange rate locked for 10 minutes",
      "floating_rate": "market rate at transaction time"
    },
    "minimum_payment": "varies by cryptocurrency, check /v1/min-amount",
    "payout_methods": [
      "single_payout",
      "batch_payout",
      "mass_payouts",
      "zero_fee_payouts_to_changenow_wallets"
    ]
  },
  "additional_info": {
    "documentation_url": "https://documenter.getpostman.com/view/7907941/2s93JusNJt",
    "status_page": "https://nowpayments.io/status-page",
    "integration_guides": "https://nowpayments.notion.site/NOWPayments-Guides-167b318f4ddb80369d28fceae41e0ca7",
    "pricing_url": "https://nowpayments.io/pricing",
    "support_url": "https://nowpayments.zendesk.com/hc/en-us/requests/new",
    "notable_features": [
      "hosted_invoices",
      "payment_buttons",
      "woocommerce_plugin",
      "mcp_for_ai_agents",
      "ipn_notifications"
    ]
  }
}

```json
{
  "tests": [
    {
      "name": "api_status_check",
      "endpoint": "/v1/status",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns API status object indicating the service is online",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "message", "type": "string", "min_length": 1}
    },
    {
      "name": "list_currencies",
      "endpoint": "/v1/currencies",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns list of supported cryptocurrencies (claimed ~300 tokens)",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "currencies", "type": "array", "min_length": 50}
    },
    {
      "name": "merchant_accepted_coins",
      "endpoint": "/v1/merchant/coins",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns list of coins the merchant account accepts",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "selectedCurrencies", "type": "array", "min_length": 1}
    },
    {
      "name": "estimate_currency_pair",
      "endpoint": "/v1/estimate",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "query_params": {
        "amount": 100,
        "currency_from": "usd",
        "currency_to": "btc"
      },
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns estimated BTC amount for 100 USD",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "estimated_amount", "type": "number", "min_value": 0}
    },
    {
      "name": "min_amount_btc",
      "endpoint": "/v1/min-amount",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "query_params": {
        "currency_from": "btc",
        "currency_to": "usd"
      },
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns minimum payment amount for BTC->USD",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "min_amount", "type": "number", "min_value": 0}
    },
    {
      "name": "payout_fee_estimate",
      "endpoint": "/v1/payout/fee",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}"
      },
      "payload": {},
      "query_params": {
        "currency": "btc",
        "amount": 0.01
      },
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns numeric payout fee; pricing doc claims 0.25% for mass payouts",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "fee", "type": "number", "min_value": 0}
    },
    {
      "name": "validate_payout_address_btc",
      "endpoint": "/v1/payout/validate-address",
      "method": "POST",
      "headers": {
        "x-api-key": "{{API_KEY}}",
        "Content-Type": "application/json"
      },
      "payload": {
        "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "currency": "btc"
      },
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Confirms a well-formed BTC bech32 address is valid",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "result", "type": "boolean"}
    },
    {
      "name": "account_balance_jwt",
      "endpoint": "/v1/balance",
      "method": "GET",
      "headers": {
        "x-api-key": "{{API_KEY}}",
        "Authorization": "Bearer {{JWT_TOKEN}}"
      },
      "payload": {},
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Returns account balances (requires JWT per auth config)",
      "metrics": ["latency", "status_code", "accuracy"],
      "validation": {"field": "balances", "type": "object"}
    },
    {
      "name": "create_invoice_happy",
      "endpoint": "/v1/invoice",
      "method": "POST",
      "headers": {
        "x-api-key": "{{API_KEY}}",
        "Content-Type": "application/json"
      },
      "payload": {
        "price_amount": 10.5,
        "price_currency": "usd",
        "order_id": "prowl-bench-invoice-001",
        "order_description": "Prowl benchmark invoice",
        "ipn_callback_url": "https://example.com/ipn",
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel"
      },
      "expected_status": 200,
      "intent": "happy_path",
      "expected_behavior": "Creates a hosted invoice and returns invoice_url / payment details",
      "metr

3/19 tests passed

{
  "overall": 34,
  "dimensions": {
    "token_efficiency": 4.0,
    "first_try_success": 2.0,
    "response_parseability": 4.0,
    "error_clarity": 5.0,
    "doc_quality": 5.0,
    "auth_simplicity": 3.0,
    "latency": 7.0,
    "consistency": 6.0
  },
  "pricing_normalized": {
    "maker_fee_bps": null,
    "taker_fee_bps": null,
    "withdrawal_fee_usd": null,
    "free_tier_requests": null
  },
  "issues": [
    "Nearly all data endpoints (/v1/currencies, /v1/merchant/coins, /v1/min-amount, /v1/estimate, /v1/payout/fee, /v1/payout/validate-address, /v1/balance) require an API key, so an agent cannot retrieve market/currency data without credentials — no public market data plane.",
    "GET /v1/estimate returns Cloudflare HTML ('Attention Required!') with status 403 instead of JSON, breaking automated parsing and blocking currency estimation entirely.",
    "POST /v1/payment (missing required field) hit a 429 Too Many Requests with an nginx HTML body — no rate-limit headers, no JSON error envelope, no Retry-After.",
    "Inconsistent error schema: some endpoints use {'status': False, 'statusCode', 'code', 'message'} while others use {'error': '...'}, forcing agents to handle multiple shapes.",
    "GET /v1/payment/0 returns 400 'payment id is required' but the endpoint path suggests an id '0' was provided — error semantics are ambiguous vs. the missing-id case.",
    "No response body on /v1/status beyond {'message': 'OK'} — no version, uptime, or rate-limit introspection for agents.",
    "Cloudflare 403 page appears on multiple endpoints, indicating unhandled bot mitigation that will unpredictably break agent traffic.",
    "No documented fee schedules, currency decimals, or quote expiry in the endpoint surface."
  ],
  "recommendations": [
    "Expose read-only market data (currencies, estimate, min-amount) without auth, or add a public unauthenticated mirror with strict rate limits.",
    "Whitelist API paths from Cloudflare bot mitigation or return JSON 403 envelopes so agents never receive HTML.",
    "Standardize on a single JSON error schema across all endpoints with fields: code, message, retry_after, and request_id.",
    "Return proper rate-limit headers (X-RateLimit-Limit/Remaining/Reset) and Retry-After on 429, with JSON body instead of nginx HTML.",
    "Add fee, precision, and quote-expiry metadata to /v1/estimate and /v1/merchant/coins responses so agents can compute totals in one call.",
    "Expand /v1/status to include API version, current rate-limit state, and per-chain health for efficient agent polling.",
    "Clarify the 400 'payment id is required' path: distinguish missing path param from the literal value '0'.",
    "Publish an OpenAPI spec documenting auth method (API key vs JWT), error codes, and rate-limit tiers."
  ]
}