Skip to main content

​
Partner API v2 Migration Guide

​
Overview

Partner API v2 replaces the REST v1 endpoints with a structured, typed REST API built on TSOA. All swap-related functionality has been migrated. Dashboard/authentication endpoints remain on v1 GraphQL.

​
Base URL

All v2 endpoints are available under /v2/ on the Partner API.

​
Authentication

Authentication remains the same:
  • Full API access: Authorization: <partnerId>:<apiSecret> header
  • Public/frontend access: partner-id: <partnerId> header (read-only endpoints)

​
Breaking Changes

​
1. Token & Chain IDs are now MongoDB ObjectIds

v1 used shortNames/symbols (e.g., "BTC", "ETH"). v2 uses MongoDB ObjectId strings for token and chain identifiers. Before (v1): 
GET /quote?from=BTC&to=ETH&amount=1
After (v2): 
GET /v2/quotes?from=<tokenObjectId>&to=<tokenObjectId>&amount=1
Use GET /v2/tokens to look up token ObjectIds by symbol, name, or address.

​
2. Quote-Driven Exchange Flow

v1 accepted from, to, and amount directly in the exchange request. v2 requires a quoteId obtained from the quotes endpoint. Before (v1): 
POST /exchange
{ "from": "BTC", "to": "ETH", "amount": 1, "addressTo": "0x..." }
After (v2): 
# Step 1: Get quote
GET /v2/quotes?from=<tokenId>&to=<tokenId>&amount=1

# Step 2: Create exchange with quoteId
POST /v2/exchanges
{ "quoteId": "<quoteId>", "addressTo": "0x..." }

​
3. MinMax Response Structure

v1 returned a flat [min, max] array. v2 returns a structured object with cex, dex, and private fields. Before (v1): 
[0.001, 10]
After (v2): 
{
  "cex": { "min": 0.001, "max": 10 },
  "dex": { "min": 0.01, "max": 5 },
  "private": { "min": 0.1, "max": 100 }
}

​
4. Order Status via Path Parameter

v1 used a query parameter. v2 uses a path parameter. Before (v1): 
GET /status?id=HOUDINI123
After (v2): 
GET /v2/orders/HOUDINI123

​
5. DEX Endpoints Use quoteId

v1 DEX endpoints (approve, allowance, chainSignatures) accepted individual route parameters. v2 uses quoteId.

​
6. Order quote Field Excluded

The quote field is no longer included in order responses. Use the separate /v2/quotes endpoint.

​
7. Paginated Responses

Token and chain listing endpoints now return paginated results with total and totalPages.

​
Endpoint Mapping

v1 Endpointv2 EndpointMethodNotes
GET /tokensGET /v2/tokensGETPaginated, uses ObjectIds
GET /dexTokensGET /v2/tokens?hasDex=trueGETMerged into tokens endpoint
GET /networksGET /v2/chainsGETObjectId for id field
GET /swapsGET /v2/swapsGETAdditional fields exposed
GET /quoteGET /v2/quotesGETMerged CEX+DEX, uses ObjectIds
GET /dexQuoteGET /v2/quotes?types=DEXGETMerged into quotes endpoint
POST /exchangePOST /v2/exchangesPOSTQuote-driven (requires quoteId)
POST /dexExchangePOST /v2/exchangesPOSTMerged into exchanges endpoint
GET /status?id={id}GET /v2/orders/{houdiniId}GETPath param instead of query
N/AGET /v2/ordersGETNEW: list orders with pagination
GET /getMinMaxGET /v2/minMaxGETStructured response object
GET /getDexMinMaxGET /v2/minMaxGETUse dex field of response
GET /volumeGET /v2/stats/volumeGETSame response shape
GET /weeklyVolumeGET /v2/stats/weeklyVolumeGETSame response shape
POST /dexConfirmTxPOST /v2/dex/confirmTxPOSTPath changed
POST /dexApprovePOST /v2/dex/approvePOSTUses quoteId
POST /dexHasEnoughAllowancePOST /v2/dex/allowancePOSTUses quoteId
POST /chainSignaturesPOST /v2/dex/chainSignaturesPOSTUses quoteId

​
New Endpoints

EndpointMethodDescription
GET /v2/ordersGETList partner orders with pagination and filtering
GET /v2/healthGETHealth check (no auth required)
GET /v2/openapi.jsonGETOpenAPI 3.0 specification
WS /v2/wsWSReal-time order status updates

​
Response Headers

All v2 responses include:
  • x-request-id - Unique request ID for debugging and support

​
Error Format

v2 uses a consistent error response format: 
{
  "status": 422,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "requestId": "uuid"
}

​
Rate Limiting

Rate limits are enforced per-partner based on tier (FREE/PRO). Limits apply to:
  • Quotes: per-minute and per-hour
  • Exchanges: per-hour
  • Read endpoints (tokens, chains, swaps, orders, stats): higher limits

​
Migration Checklist

  • Look up token ObjectIds via GET /v2/tokens?symbol=BTC
  • Update exchange flow to quote-driven (get quote first, then exchange with quoteId)
  • Update order status calls to use path parameter
  • Update DEX approval/allowance calls to use quoteId
  • Parse new structured minmax response format
  • Handle paginated responses for token/chain listings
  • Update error handling for new error format
  • Test with GET /v2/health to verify connectivity