> ## Documentation Index
> Fetch the complete documentation index at: https://docs.houdini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration V1 to V2

> Migrate from Partner API v1 to v2

> [!CAUTION]
>
> Deprecation of the REST v1 swap endpoints begins on September 30, 2026. Please migrate to the Partner API v2. Dashboard and authentication endpoints remain on v1 GraphQL and are not affected. [Read the migration guide](https://docs.houdiniswap.com/migration/v1-to-v2)

# 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):**

```text theme={null}
GET /quote?from=BTC&to=ETH&amount=1
```

**After (v2):**

```text theme={null}
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):**

```text theme={null}
POST /exchange
{ "from": "BTC", "to": "ETH", "amount": 1, "addressTo": "0x..." }
```

**After (v2):**

```text theme={null}
# 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):**

```json theme={null}
[0.001, 10]
```

**After (v2):**

```json theme={null}
{
  "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):**

```text theme={null}
GET /status?id=HOUDINI123
```

**After (v2):**

```text theme={null}
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](https://docs.houdini.com/developer-hub/core-concepts/partner-stats.md) |
| `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/status` | GET | System 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:

```json theme={null}
{
  "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/status` to verify connectivity


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.