Migration from API v1

Upgrade from Nexchange API v1 to the improved v2 interface with cleaner field names, better structure, and enhanced developer experience while maintaining full backward compatibility.

Why Upgrade to API v2?

Key Improvements in v2

• 🎯 Intuitive Field Names: side instead of order_type, deposit_amount instead of amount_quote
• 📊 Flat Structure: No nested objects, all fields at the top level
• 🔤 String Values: "BUY" instead of numeric codes like 0
• 🧹 Cleaner Responses: Removed deprecated and unnecessary fields
• 📝 Better Documentation: More descriptive field names and clearer concepts
• 🔗 Consistent Endpoints: Simplified URL structure and standardized naming
• 🔐 API Key Required: All endpoints now require API key authentication for security

Base URL Changes

v1 Base URL:

https://api.n.exchange/en/api/v1/

v2 Base URL:

https://api.n.exchange/en/api/v2/

Field Mapping Reference

Orders

v1 Field	v2 Field	Change Type	Description
order_type	side	Renamed	Now uses "BUY" or "SELL" strings
amount_base	withdraw_amount	Renamed	More descriptive naming
amount_quote	deposit_amount	Renamed	More descriptive naming
pair.base	withdraw_currency	Flattened	Currency code only (string)
pair.quote	deposit_currency	Flattened	Currency code only (string)
status_name[0][1]	status	Simplified	Flat string status
payment_window	payment_window_minutes	Renamed	Clearer units
payment_deadline	fixed_rate_deadline	Renamed	More descriptive
transactions[].tx_id	deposit_transaction, withdraw_transaction	Split	Separate fields by type

Pairs

v1 Field	v2 Field	Change Type	Description
base	to	Renamed	Currency you receive
quote	from	Renamed	Currency you send
fee_ask, fee_bid	removed	Deprecated	Simplified response
test_mode	removed	Deprecated	No longer needed
orderbook_enabled	removed	Deprecated	No longer needed
reverse_orderbook_enabled	removed	Deprecated	No longer needed

Rates

v1 Field	v2 Field	Change Type	Description
max_receive_amount	max_withdraw_amount	Renamed	More descriptive
min_receive_amount	min_withdraw_amount	Renamed	More descriptive
allowed_historic_price_variance	removed	Deprecated	No longer needed
allowed_historic_price_age	removed	Deprecated	No longer needed
max_amount	removed	Deprecated	Replaced by specific limits
min_amount	removed	Deprecated	Replaced by specific limits

Pre-screening

v1 Field	v2 Field	Change Type	Description
amount_quote	deposit_amount	Renamed	More descriptive
amount_base	withdraw_amount	Renamed	More descriptive
detail	status, message	Split	Structured response

Endpoint Changes

Currency Endpoints

v1 Endpoint	v2 Endpoint	Changes
GET /currency/	GET /currency/	✅ Same endpoint
GET /currency/{code}/	GET /currency/{code}/	✅ Same endpoint
-	GET /network/	🆕 New: List networks
-	GET /network/{name}/	🆕 New: Get network details

Trading Pair Endpoints

v1 Endpoint	v2 Endpoint	Changes
GET /pair/	GET /pair/	✅ Same endpoint, simplified response
GET /pair/{name}/	GET /pair/{name}/	✅ Same endpoint, simplified response

Rate Endpoints

v1 Endpoint	v2 Endpoint	Changes
GET /info/bulk/	GET /rate/	🔄 Renamed: Cleaner endpoint name

Order Endpoints

v1 Endpoint	v2 Endpoint	Changes
GET /orders/	GET /orders/	✅ Same endpoint, simplified response
POST /orders/	POST /orders/	✅ Same endpoint, simplified request/response
GET /orders/{unique_reference}/	GET /orders/{unique_reference}/	✅ Same endpoint, simplified response
PATCH /orders/{unique_reference}/	PATCH /orders/{unique_reference}/	✅ Same endpoint, simplified request

Risk Management Endpoints

v1 Endpoint	v2 Endpoint	Changes
POST /pre_screening/	POST /pre_screening/	✅ Same endpoint, structured response

Migration Examples

1. Get Trading Pairs

v1 Endpoint:

curl -X GET "https://api.n.exchange/en/api/v1/pair/" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey api_key"

v1 Response:

[
  {
    "name": "BTCUSDC",
    "base": "BTC",
    "quote": "USDC",
    "fee_ask": "0.005",
    "fee_bid": "0.005",
    "disabled": false,
    "test_mode": false,
    "orderbook_enabled": true,
    "reverse_orderbook_enabled": false
  }
]

v2 Endpoint:

curl -X GET "https://api.n.exchange/en/api/v2/pair/" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey api_key"

v2 Response:

[
  {
    "name": "BTCUSDC",
    "to": "BTC",
    "from": "USDC",
    "disabled": false
  }
]

2. Get Rates

v1 Endpoint:

curl -X GET "https://api.n.exchange/en/api/v1/info/bulk/" \
  -H "Accept: application/json" \ 
  -H "Authorization: ApiKey api_key"

v1 Response:

[
  {
    "pair": "BTCUSDC",
    "rate": "45000.00",
    "max_receive_amount": "10.00000000",
    "min_receive_amount": "0.00100000",
    "allowed_historic_price_variance": "0.05",
    "allowed_historic_price_age": "300",
    "max_amount": "500000.00",
    "min_amount": "50.00"
  }
]

v2 Endpoint:

curl -X GET "https://api.n.exchange/en/api/v2/rate/" \
  -H "Accept: application/json" \ 
  -H "Authorization: ApiKey api_key"

v2 Response:

[
  {
    "pair": "BTCUSDC",
    "from": "USDC",
    "to": "BTC",
    "withdrawal_fee": "0.00050000",
    "rate": "45000.00",
    "rate_id": "abc123-000000",
    "max_withdraw_amount": "10.00000000",
    "min_withdraw_amount": "0.00100000",
    "max_deposit_amount": "500000.00",
    "min_deposit_amount": "50.00",
    "expiration_time_unix": "1697365800"
  }
]

3. Create Order

v1 Endpoint:

curl -X POST "https://api.n.exchange/en/api/v1/orders/" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey api_key" \
  -d '{
    "amount_base": "0.01000000",
    "pair_name": "BTCUSDC",
    "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  }'

v1 Request:

{
  "amount_base": "0.01000000",
  "pair_name": "BTCUSDC",
  "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
}

v2 Endpoint:

curl -X POST "https://api.n.exchange/en/api/v2/orders/" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey api_key" \
  -d '{
    "side": "SELL",
    "withdraw_amount": "0.01000000",
    "deposit_currency": "USDC",
    "withdraw_currency": "BTC",
    "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  }'

v2 Request:

{
  "side": "SELL",
  "withdraw_amount": "0.01000000",
  "deposit_currency": "USDC",
  "withdraw_currency": "BTC",
  "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
}

4. Pre-screening Request

v1 Request:

{
  "ip": "192.168.1.1",
  "pair": "BTCUSDC",
  "amount_quote": "50000.0"
}

v1 Response:

{
  "detail": "Pre-screening passed."
}

v2 Request:

{
  "ip": "192.168.1.1",
  "pair": "BTCUSDC",
  "deposit_amount": "50000.0"
}

v2 Response:

{
  "status": "success",
  "message": "Pre-screening passed."
}

Step-by-Step Migration

Step 1: Update Base URLs

Update all your API calls to use the v2 base URL:

// Before (v1)
const BASE_URL = 'https://api.n.exchange/en/api/v1/';

// After (v2)
const BASE_URL = 'https://api.n.exchange/en/api/v2/';

Step 2: Update Endpoint URLs

Replace changed endpoint names:

// Before (v1)
const ratesUrl = `${BASE_URL}info/bulk/`;

// After (v2)
const ratesUrl = `${BASE_URL}rate/`;

Step 3: Add Authorization header

"Authorization: ApiKey api_key"

Step 4: Update Field Names

Replace old field names with new ones:

// Before (v1)
const orderData = {
  amount_base: "0.01",
  pair_name: "BTCUSDC",
  order_type: 0  // numeric code
};

// After (v2)
const orderData = {
  withdraw_amount: "0.01",
  deposit_currency: "USDC",
  withdraw_currency: "BTC", 
  side: "SELL"  // string value
};

Step 5: Handle Response Changes

Update response parsing logic:

// Before (v1) - nested pair structure
const baseCurrency = response.pair.base;
const quoteCurrency = response.pair.quote;
const status = response.status_name[0][1];

// After (v2) - flat structure
const withdrawCurrency = response.withdraw_currency;
const depositCurrency = response.deposit_currency;
const status = response.status;

Step 6: Remove Deprecated Fields

Remove handling of deprecated fields:

// Remove these from v1 response parsing:
// - fee_ask, fee_bid
// - test_mode, orderbook_enabled
// - allowed_historic_price_variance
// - allowed_historic_price_age
// - max_amount, min_amount (use specific limits instead)

Migration Checklist

• Update base URLs from /v1/ to /v2/
• Replace amount_base with withdraw_amount
• Replace amount_quote with deposit_amount
• Replace nested pair.base with flat withdraw_currency
• Replace nested pair.quote with flat deposit_currency
• Replace order_type numeric values with side strings
• Update status parsing from status_name[0][1] to status
• Replace /info/bulk/ with /rate/ endpoint
• Update transaction handling from nested arrays to flat fields
• Remove handling of deprecated fields
• Update pre-screening response parsing to use status and message
• Test all endpoints with new field names
• Update error handling for new response format

Backward Compatibility

Don't worry about breaking changes:

• v1 endpoints remain fully functional - No rush to migrate
• Same business logic - v2 inherits all v1 functionality
• Gradual migration - Migrate endpoints one by one
• Side-by-side operation - Run both versions simultaneously during transition

New Features in v2

Enhanced Filtering

• Rate filtering: fiat_only and crypto_only query parameters
• Pair pagination: Better pagination support for large lists

Network Information

• Network endpoints: New /network/ endpoints for blockchain network details
• Enhanced currency info: Better token and network information

Improved Error Handling

• Structured errors: Consistent error response format across all endpoints
• Detailed validation: Field-specific error messages

Need Help?

• 📚 v2 API Reference - Complete v2 documentation
• 💬 Support - Contact our team for migration assistance

Ready to start? Try our Quick Start Guide guide! 🚀

Next Steps

• Quick Start - Get started with API v2
• API Reference - Complete v2 documentation
• FAQ - Frequently asked questions

---

Questions about migration? Contact our support team for assistance with upgrading your integration.