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. All API v2 endpoints require API key authentication for security. Additionally, these endpoints require OAuth2:

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

API Key Required. All API v2 endpoints require API key authentication for security:

• 🔐 API Key required: All endpoints including creating orders, fetching order status, price discovery
• 🔐 OAuth2 required: Order history, updating existing orders with refund/payout addresses

While OAuth2 is still optional for basic operations, all v2 endpoints require an API key in the Authorization header.

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 side mean? ("BUY" vs "SELL")

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

• All swap sides are "BUY" - which is also the default
• The side parameter is not mandatory for crypto swaps
• "SELL" and "BUY" are primarily for fiat trading pairs

What do withdraw_amount and deposit_amount mean?

For buy orders (crypto swaps):

• withdraw_amount: Amount the user receives (destination currency)
• deposit_amount: 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:

• withdraw_amount: 0.1 (ETH - what they receive)
• deposit_amount: 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 /rate are currently active and supported. While /pair returns all pairs we have, some might not be active for trading.

Recommendation: Use /rate 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 Code	Status Name	Description
0	CANCELED	Deposit not received and order expired
11	INITIAL	Order created, awaiting deposit
12	UNCONFIRMED PAYMENT	Deposit detected but not confirmed
13	PAID	Deposit confirmed
14	PRE-RELEASE	Withdrawal transaction being created
15	RELEASED	Withdrawal transaction broadcasted
16	COMPLETED	Withdrawal transaction confirmed
6	INITIATED REFUND	Order refund process initiated
8	REFUNDED	Order refunded successfully
7	REFUND FAILED	Order refund failed
9	PENDING KYC	Waiting 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 Code	Status Name	Description
-10	FAILED	Transaction failed
-5	DROPPED	Transaction dropped
-1	AUDIT_FAILED	Failed audit (withdrawal only)
0	CANCELED	Transaction canceled (withdrawal only)
1	INITIAL	Initial state (withdrawal only)
4	STAGED	Transaction staged (withdrawal only)
7	AUDITED	Transaction audited (withdrawal only)
10	UNCONFIRMED	Transaction broadcasted but unconfirmed
13	CONFIRMED	Transaction 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_minutes and fixed_rate_deadline mean?

• payment_window_minutes: Duration in minutes for payment deadline
• fixed_rate_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. All v2 endpoints require API key authentication, though OAuth2 is not needed for most use cases since:

• All orders are created with anonymous users
• Only API key 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?

All v2 endpoints require API key authentication. Additionally, these endpoints require OAuth2:

• /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 /rate?

/rate (/info/bulk in API v1):

• Provides rate and fee information for all pairs
• Returns rate and fees values
• Good for getting current rates for rate_id usage
• Supports enhanced filtering with fiat_only and crypto_only query parameters

/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 /rate for getting rate_ids and general rate information

Example:

Rate from /rate: 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 /rate 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 in API v2. The network field should now be properly populated for all crypto currencies where is_crypto is true. Additionally, v2 provides new /network/ endpoints for detailed blockchain network information.

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 fixed_rate_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 /rate
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 for user’s order and transaction updates, 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?

• API V2 Documentation: https://api.n.exchange/docs/v2
• Legac V1 Documentation: https://nexchange2.docs.apiary.io/ (deprecated)
• Support Email: support@n.exchange
• Developer Email: support@n.exchange
• Business Inquiries: support@n.exchange

Integration Support

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