Skip to main content
Version: v1

FAQ

Comprehensive questions and answers based on developer integration experiences with the Nexchange API.

Authentication & OAuth2​

What is the client_id parameter for the /oauth2/token endpoint?​

For grant_type = password, the client_id parameter is your unique OAuth2 application identifier that distinguishes one OAuth2 app from another. However, authentication is not currently required to initiate a swap. Most endpoints work without authentication, including:

  • Price discovery
  • Order creation
  • Order status checking

Only these endpoints require authentication:

  • Order history (/user/me/orders)
  • PATCH requests to existing orders (/orders/:id or /users/me)

Is there a grant_type called refresh_token?​

Yes, there is a refresh_token grant type to fetch access tokens using refresh tokens. However, OAuth2 is not required for most use cases involving swaps and order management.

Do I need OAuth2 authentication for placing orders?​

No. Authentication is optional for most operations:

  • ✅ No auth needed: Creating orders, fetching order status, price discovery
  • 🔐 Auth required: Order history, updating existing orders with refund/payout addresses

You can implement the core swap functionality without authentication and add it later if needed.

Orders & Trading​

What is x-referral-token?​

The x-referral-token is your unique referral token which:

  • Secures your revenue share under your account
  • Applies the commercial terms agreed upon for end users (rates TTL and markup/fees)
  • Maps orders to your referral code for tracking and commission purposes

What does order_type mean? (0 = sell, 1 = buy)​

This API supports both fiat and crypto. For cryptocurrency swaps:

  • All swap order types are "buy" (1) - which is also the default
  • The order_type parameter is not mandatory for crypto swaps
  • 0 = sell and 1 = buy are primarily for fiat trading pairs

What do amount_base and amount_quote mean?​

For buy orders (crypto swaps):

  • amount_base: Amount the user receives (destination currency)
  • amount_quote: Amount the user sends (source currency)

You can provide either field, and the API will calculate the other based on the provided rate. For best UX, send whichever field the user interacted with last to reflect their intent.

Example: For a BTC→ETH swap where user wants 0.1 ETH:

  • amount_base: 0.1 (ETH - what they receive)
  • amount_quote: calculated automatically (BTC - what they send)

What is the payment_method parameter?​

This parameter is for fiat transactions only. For cryptocurrency swaps, you can disregard this parameter.

What do withdraw_address and refund_address mean?​

withdraw_address: The destination address where the receiving currency is sent after the swap.

refund_address: The address where funds are sent from (source address). This serves three purposes:

  1. Transaction Monitoring: We monitor this address to detect when payment is sent to us
  2. Compliance Screening: We perform on-chain compliance screening to check for criminal/illicit exposure
  3. Refund Capability: In rare cases requiring additional KYC/verification, we can refund to this address
Important

Only use addresses that will actually participate in the transaction:

  • UTXO currencies: Use the specific address that will be used as input
  • EVM/Account-based currencies: Use the address funds will be sent directly from

Is the deposit_address where users send their funds?​

Yes. The deposit_address in the order response is the wallet address where users must send their trade amount.

Are there currency pairs that aren't supported?​

All pairs returned by /info/bulk are currently active and supported. While /pair returns all pairs we have, some might not be active for trading.

Recommendation: Use /info/bulk for active trading pairs rather than /pair.

For unsupported direct pairs (like DOGE/SOL), n.exchange handles the routing automatically - you don't need to find middle currencies or perform multi-step transactions.

Order Status & Processing​

What are the possible order states?​

Status CodeStatus NameDescription
0CANCELEDDeposit not received and order expired
11INITIALOrder created, awaiting deposit
12UNCONFIRMED PAYMENTDeposit detected but not confirmed
13PAIDDeposit confirmed
14PRE-RELEASEWithdrawal transaction being created
15RELEASEDWithdrawal transaction broadcasted
16COMPLETEDWithdrawal transaction confirmed
6INITIATED REFUNDOrder refund process initiated
8REFUNDEDOrder refunded successfully
7REFUND FAILEDOrder refund failed
9PENDING KYCWaiting for additional due diligence

What is the typical order flow?​

✅ Success Flow:

INITIAL → UNCONFIRMED PAYMENT → PAID → PRE-RELEASE → RELEASED → COMPLETED

❌ Unpaid Flow:

INITIAL → CANCELED

🔍 KYC Success Flow:

INITIAL → UNCONFIRMED PAYMENT → PENDING KYC → PAID → PRE-RELEASE → RELEASED → COMPLETED

🔍 KYC Failure Flow:

INITIAL → UNCONFIRMED PAYMENT → PENDING KYC → INITIATED REFUND → REFUNDED

🔄 Refund Retry Flow:

INITIATED REFUND → REFUND FAILED → INITIATED REFUND → REFUNDED

What are the transaction states?​

Transaction objects are nested in order responses with their own state machine:

Status CodeStatus NameDescription
-10FAILEDTransaction failed
-5DROPPEDTransaction dropped
-1AUDIT_FAILEDFailed audit (withdrawal only)
0CANCELEDTransaction canceled (withdrawal only)
1INITIALInitial state (withdrawal only)
4STAGEDTransaction staged (withdrawal only)
7AUDITEDTransaction audited (withdrawal only)
10UNCONFIRMEDTransaction broadcasted but unconfirmed
13CONFIRMEDTransaction confirmed

Normal Withdrawal Flow:

INITIAL → STAGED → AUDITED → UNCONFIRMED → CONFIRMED

Deposit Transactions start at UNCONFIRMED status.

When is user_marked_as_paid true/false?​

This field is primarily for fiat orders, not crypto swaps. It allows:

  1. Users to inform us that non-instant payments (bank transfers) are complete
  2. Partners to inform us that transactions to deposit addresses were signed and published

Usage: PATCH /orders/:id with payload {'user_marked_as_paid': true}

This is not mandatory - we automatically detect payments by monitoring blockchain networks.

What do payment_window and payment_deadline mean?​

  • payment_window: Duration in minutes for payment deadline
  • payment_deadline: Specific UTC timestamp when payment expires

These apply only to the user's deposit deadline, not n.exchange's processing time.

How does is_custody impact processing times?​

is_custody makes processing faster because we control both deposit and withdrawal vaults, allowing:

  • 0 confirmations for UTXO currencies
  • 1 confirmation for EVM currencies
  • Both directions (deposit and withdrawal)

User Management & Order History​

Is there an endpoint to get all orders for a user?​

For partners: We typically provide quarterly CSV reports with custom data you request rather than a real-time API endpoint.

For monitoring: Most partners use long-polling on individual orders via /orders/{REF} while orders are in active status.

Authentication: The user orders endpoint (/user/me/orders) requires OAuth2 authentication, but this is not needed for most use cases since:

  • All orders are created with anonymous users
  • No authorization needed for basic order operations

How are orders mapped to users?​

Orders are mapped using the x-referral-token header:

  • Each order is assigned an anonymous user
  • Your referral token maps the order to your account for commission tracking
  • No username/password required

What other endpoints require authentication?​

Only these endpoints require authentication:

  • /user/me/orders (order history)
  • PATCH /orders/:id (updating existing orders)
  • /users/me (user information)
  • Fiat-related endpoints (payment method management, etc.)

Pricing & Rate Management​

What's the difference between /get_prices/{PAIR} and /info/bulk?​

/info/bulk:

  • Provides rate and fee information for all pairs
  • Returns rate and fees values
  • Good for getting current rates for rate_id usage

/get_prices/{PAIR}:

  • Provides calculated quote amounts for specific base amounts
  • Returns exact quote_amount for the requested base_amount
  • Better for displaying user-facing quote amounts

Recommendation:

  • Use /get_prices/{PAIR} for user-facing quotes as it provides the exact amount
  • Use /info/bulk for getting rate_ids and general rate information

Example:

Rate from /info/bulk: 0.06175520000000
Quote from /get_prices: 0.0617871771692 (more precise for 1 SOL)

How do I get the most accurate quote amount?​

Use /get_prices/{PAIR} with the specific base_amount the user wants to trade. This provides the most accurate quote that accounts for:

  • Current market rates
  • Fees and spreads
  • Precise decimal calculations

Don't calculate manually with base_amount * rate from /info/bulk as this may not account for all factors.

Transaction Management​

Can I cancel a transaction after it's in INITIAL state?​

Yes. Use the PATCH method on the order endpoint:

  • To cancel: Send 'user_marked_as_paid': false
  • To mark as paid: Send 'user_marked_as_paid': true (optionally include deposit tx ID for faster processing)

Is the deposit address the same for every order?​

It depends on your integration:

  • If you include refund/sender address in order creation: We can use a single deposit address strategy
  • If you don't include refund/sender address: We use a rotating address strategy

Including the refund address allows us to allocate deposits to orders more efficiently.

Why do some currencies show 'None' for network parameter?​

This has been fixed. The network field should now be properly populated for all crypto currencies where is_crypto is true.

Which Bitcoin network should I use?​

For Bitcoin, we support:

  • Segwit addresses (recommended)
  • Legacy addresses

Use standard Bitcoin mainnet - we don't require specific wallet implementations.

Why are is_completed and is_verified still false when order status is COMPLETED?​

This can be expected behavior in some cases. The order status COMPLETED indicates the overall workflow is finished, but individual transaction flags may have different update timing.

If you're seeing this consistently and it affects your integration, please contact support for clarification on your specific use case.

Processing Times & Monitoring​

How long does order processing take?​

View current processing time statistics at: https://api.n.exchange/en/orders/order_processing_times/?exclude_btc=on

The displayed times include the entire timeframe from:

  • Start: Order creation (not payment)
  • End: Withdrawal transaction receiving 1 confirmation

Note: BTC is excluded by default from these statistics.

Does every transaction status change affect order status?​

Yes. Examples:

  • Deposit transaction: UNCONFIRMED → CONFIRMED causes order: UNCONFIRMED PAYMENT → PAID
  • Withdrawal transaction: UNCONFIRMED → CONFIRMED causes order: RELEASED → COMPLETED

However, confirmation count updates may not necessarily change transaction status.

How should I monitor order progress?​

Recommended approach:

  1. Poll order endpoint /orders/{unique_reference} regularly
  2. Monitor order status for major state changes
  3. Check transaction objects within orders for detailed progress
  4. Implement timeout handling based on payment_deadline

Optional enhancement:

  • Send user_marked_as_paid: true with deposit tx ID for faster processing
  • Monitor refund address for outgoing transactions (though we handle this automatically)

Error Handling & Best Practices​

What should I do if compliance screening fails?​

If an order fails compliance screening, you'll receive a 400 status code with an appropriate error message. You can:

  1. Use /pre_screening endpoint to check addresses before creating orders
  2. Handle 400 responses gracefully and inform users appropriately
  3. Don't retry with the same address if it fails screening

What's the best practice for handling rate TTL?​

  1. Get fresh rates regularly using /info/bulk
  2. Use rate_id from recent rate data when creating orders
  3. Handle rate expiration errors gracefully
  4. Don't cache rates for extended periods

Should I implement webhooks?​

While we don't currently offer websocket endpoints, you can:

  • Implement polling with reasonable intervals (30-60 seconds for active orders)
  • Send transaction notifications via user_marked_as_paid for faster processing
  • Monitor blockchain directly for deposit confirmations if needed

Still Have Questions?​

Integration Support

For complex integration questions or custom requirements, our developer support team is here to help at support@nexchange.io