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 Endpoint	v2 Endpoint	Method	Notes
`GET /tokens`	`GET /v2/tokens`	GET	Paginated, uses ObjectIds
`GET /dexTokens`	`GET /v2/tokens?hasDex=true`	GET	Merged into tokens endpoint
`GET /networks`	`GET /v2/chains`	GET	ObjectId for `id` field
`GET /swaps`	`GET /v2/swaps`	GET	Additional fields exposed
`GET /quote`	`GET /v2/quotes`	GET	Merged CEX+DEX, uses ObjectIds
`GET /dexQuote`	`GET /v2/quotes?types=DEX`	GET	Merged into quotes endpoint
`POST /exchange`	`POST /v2/exchanges`	POST	Quote-driven (requires `quoteId`)
`POST /dexExchange`	`POST /v2/exchanges`	POST	Merged into exchanges endpoint
`GET /status?id={id}`	`GET /v2/orders/{houdiniId}`	GET	Path param instead of query
N/A	`GET /v2/orders`	GET	NEW: list orders with pagination
`GET /getMinMax`	`GET /v2/minMax`	GET	Structured response object
`GET /getDexMinMax`	`GET /v2/minMax`	GET	Use `dex` field of response
`GET /volume`	`GET /v2/stats/volume`	GET	Partner-scoped; 4 new fields added — see Partner Stats
`GET /weeklyVolume`	`GET /v2/stats/weeklyVolume`	GET	Partner-scoped; same response shape
`POST /dexConfirmTx`	`POST /v2/dex/confirmTx`	POST	Path changed
`POST /dexApprove`	`POST /v2/dex/approve`	POST	Uses `quoteId`
`POST /dexHasEnoughAllowance`	`POST /v2/dex/allowance`	POST	Uses `quoteId`
`POST /chainSignatures`	`POST /v2/dex/chainSignatures`	POST	Uses `quoteId`

New Endpoints

Endpoint	Method	Description
`GET /v2/orders`	GET	List partner orders with pagination and filtering
`GET /v2/stats/chart`	GET	Time-series chart data with date range and granularity filtering
`GET /v2/health`	GET	Health check (no auth required)
`GET /v2/openapi.json`	GET	OpenAPI 3.0 specification
`WS /v2/ws`	WS	Real-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

Overview

Swap Flow Guides

CEX Endpoints

DEX Endpoints

Utilities

Troubleshooting

Migration V1 to V2

Partner API v2 Migration Guide

Overview

Base URL

Authentication

Breaking Changes

1. Token & Chain IDs are now MongoDB ObjectIds

2. Quote-Driven Exchange Flow

3. MinMax Response Structure

4. Order Status via Path Parameter

5. DEX Endpoints Use quoteId

6. Order `quote` Field Excluded

7. Paginated Responses

Endpoint Mapping

New Endpoints

Response Headers

Error Format

Rate Limiting

Migration Checklist

​Partner API v2 Migration Guide

​Overview

​Base URL

​Authentication

​Breaking Changes

​1. Token & Chain IDs are now MongoDB ObjectIds

​2. Quote-Driven Exchange Flow

​3. MinMax Response Structure

​4. Order Status via Path Parameter

​5. DEX Endpoints Use quoteId

​6. Order quote Field Excluded

​7. Paginated Responses

​Endpoint Mapping

​New Endpoints

​Response Headers

​Error Format

​Rate Limiting

​Migration Checklist

Partner API v2 Migration Guide

Overview

Base URL

Authentication

Breaking Changes

1. Token & Chain IDs are now MongoDB ObjectIds

2. Quote-Driven Exchange Flow

3. MinMax Response Structure

4. Order Status via Path Parameter

5. DEX Endpoints Use quoteId

6. Order `quote` Field Excluded

7. Paginated Responses

Endpoint Mapping

New Endpoints

Response Headers

Error Format

Rate Limiting

Migration Checklist