> ## Documentation Index > Fetch the complete documentation index at: https://docs.houdiniswap.com/llms.txt > Use this file to discover all available pages before exploring further. # Create exchange > Create a new exchange (swap). Use `type: "private"` or `type: "standard"` for centralized exchanges or `type: "dex"` for decentralized exchanges. ## OpenAPI ````yaml https://api-partner.houdiniswap.com/v2/openapi.json post /exchanges openapi: 3.0.0 info: title: houdiniswap-backend version: 2.1.2 description: Houdiniswap Backend license: name: ISC contact: {} servers: - url: https://api-partner.houdiniswap.com/v2 security: [] paths: /exchanges: post: tags: - Exchanges summary: Create exchange description: >- Create a new exchange (swap). Use `type: "private"` or `type: "standard"` for centralized exchanges or `type: "dex"` for decentralized exchanges. operationId: CreateExchange parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExchangeRequest' responses: '200': description: Exchange created content: application/json: schema: $ref: '#/components/schemas/OrderV2PublicResponse' examples: Example 1: value: houdiniId: example-houdini-id created: '2026-01-01T12:00:00.000Z' depositAddress: bc1qexampledepositaddress000000000000000000 receiverAddress: '0x9f1f9a5c0f1d9a5c0f1d9a5c0f1d9a5c0f1d9a5c' anonymous: false expires: '2026-01-01T12:30:00.000Z' status: 0 inAmount: 0.25 inSymbol: BTC outAmount: 3.52 outSymbol: ETH displayStatus: WAITING_FOR_DEPOSIT '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKey: [] components: schemas: ExchangeRequest: description: Request body for creating a new exchange properties: addressTo: type: string description: Destination wallet address where funds will be sent minLength: 1 maxLength: 200 quoteId: type: string description: >- Quote ID from a prior quote response. Amount, from token, to token, and swap provider are retrieved from the provided quote. For CEX exchanges, if the exchange fails with the chosen swap provider, it will fallback to the next best route. addressFrom: type: string description: Source wallet address (required for DEX, ignored for CEX) refundAddress: type: string description: |- Sender's wallet address for refunds if a fixed-rate swap fails. Required when the quote was created with fixed: true. maxLength: 200 refundExtraId: type: string description: >- Memo/tag for refundAddress on memo-bearing chains (e.g. XRP DestinationTag, Stellar memo, TON comment). Ignored when the destination chain has no memo concept. maxLength: 64 signatures: items: $ref: '#/components/schemas/SignatureObject' type: array description: EIP-712 signatures for permit-based approvals (DEX only) destinationTag: type: string description: Destination tag / memo (e.g. for XRP, XLM) maxLength: 64 walletInfo: type: string description: Wallet info string maxLength: 256 required: - addressTo - quoteId type: object additionalProperties: false OrderV2PublicResponse: properties: swapName: type: string fixed: type: boolean refundAddress: type: string houdiniId: type: string created: type: string format: date-time modified: type: string format: date-time depositAddress: type: string description: The CEX deposit address where the user must send funds receiverAddress: type: string anonymous: type: boolean expires: type: string format: date-time status: $ref: '#/components/schemas/OrderStatus' inAmount: type: number format: double inSymbol: type: string outAmount: type: number format: double outSymbol: type: string depositTag: type: string description: Memo/tag required when depositing funds for assets that use one notified: type: boolean eta: type: number format: double description: ETA time, depending on swap inAmountUsd: type: number format: double description: USD value of the input amount at order creation time. outAmountUsd: type: number format: double multiId: type: string inCreated: type: string format: date-time id: type: string nonRefundable: type: boolean metadata: {} isDex: type: boolean orderFinishedReceived: type: string format: date-time actionRequired: type: boolean outToken: $ref: '#/components/schemas/Token' inToken: $ref: '#/components/schemas/Token' inStatus: $ref: '#/components/schemas/Status' outStatus: $ref: '#/components/schemas/Status' outTransactionOutHash: type: string displayStatus: $ref: '#/components/schemas/DisplayStatus' receiverTag: type: string nullable: true description: Memo/tag required when receiving funds for assets that use one required: - swapName - houdiniId - created - depositAddress - receiverAddress - anonymous - expires - status - inAmount - inSymbol - outAmount - outSymbol - notified - eta - inAmountUsd - outAmountUsd - multiId - inCreated - id - isDex - orderFinishedReceived - actionRequired - outToken - inToken - inStatus - outStatus - outTransactionOutHash - displayStatus type: object additionalProperties: false ValidationError: properties: message: type: string code: type: string requestId: type: string fields: $ref: '#/components/schemas/FieldErrors' required: - message - code - fields type: object additionalProperties: false ErrorResponse: properties: message: type: string code: type: string requestId: type: string required: - message - code type: object additionalProperties: false SignatureObject: properties: signature: type: string key: type: string swapRequiredMetadata: $ref: '#/components/schemas/Record_string.any_' required: - signature - key type: object additionalProperties: false OrderStatus: description: |- - **-2** Order is being initialized (label: INITIALIZING) - **-1** Order initialized (label: NEW) - **0** Waiting for deposit confirmation (label: WAITING) - **1** Deposit is being confirmed (label: CONFIRMING) - **2** Exchange is in progress (label: EXCHANGING) - **3** Order is going through anonymization (label: ANONYMIZING) - **4** Order completed successfully (label: FINISHED) - **5** Order has expired (label: EXPIRED) - **6** Order failed (label: FAILED) - **7** Order was refunded (label: REFUNDED) - **8** Order was deleted (label: DELETED) enum: - -2 - -1 - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 type: number Token: properties: icon: type: string id: type: string address: type: string nullable: true chain: type: string decimals: type: number format: double default: 0 symbol: type: string default: '' name: type: string default: '' created: type: string format: date-time modified: type: string format: date-time chainData: $ref: '#/components/schemas/Chain' description: type: string nullable: true mainnet: type: boolean enabled: type: boolean unverified: type: boolean hasDex: type: boolean hasCex: type: boolean hasBundler: type: boolean description: >- Indicates whether the token can be used in a bundle (multiswap) swap. True for CEX-routable Solana tokens, and for EVM native assets plus Pimlico-listed ERC-20s on Pimlico-supported chains. hasSelfPrivate: type: boolean description: >- Indicates if token supports private (self-to-self) swaps. Stored field computed when token is saved. True when token has CEX support AND at least 2 enabled CEX swap provider mappings. cexTokenId: type: string default: '' rank: type: number format: double nullable: true cgId: type: string nullable: true marketCapChange24h: type: number format: double description: 24h market cap change percentage from CoinGecko. circulatingSupply: type: number format: double description: Token circulating supply from CoinGecko. price: type: number format: double nullable: true marketCap: type: number format: double nullable: true volume: type: number format: double nullable: true fdv: type: number format: double nullable: true change: type: number format: double nullable: true priority: type: number format: double nullable: true warningMessage: type: string securityScan: $ref: '#/components/schemas/TokenSecurityScan' description: >- HS-1835: last security verdict for this token, with the provider's full response and an `expiresAt` driving re-scan. Absent until the token has been selected as a swap source or destination at least once. required: - icon - id - chain - created - chainData type: object additionalProperties: false Status: description: |- - **0** New swap - **1** Waiting for confirmation - **2** Being confirmed - **3** Exchange in progress - **4** Sending to destination - **5** Swap completed - **6** Swap failed - **7** Swap refunded - **8** Verifying swap - **9** Swap expired - **10** Fallback mode enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 type: number DisplayStatus: enum: - WAITING_FOR_DEPOSIT - DEPOSIT_DETECTED - EXCHANGE_IN_PROGRESS - SENDING_TO_INTERMEDIARY - REACHED_INTERMEDIARY - INITIATING_SECOND_EXCHANGE - SECOND_EXCHANGE_IN_PROGRESS - SENDING_TO_RECEIVER - SWAP_COMPLETED - EXPIRED - FAILED - REFUNDED - DELETED type: string FieldErrors: properties: {} type: object additionalProperties: properties: value: {} message: type: string required: - message type: object Record_string.any_: properties: {} additionalProperties: {} type: object description: Construct a type with a set of properties K of type T Chain: properties: icon: type: string addressValidation: type: string tokenAddressValidation: type: string id: type: string created: type: string format: date-time modified: type: string format: date-time name: type: string shortName: type: string memoNeeded: type: boolean nullable: true hashUrl: type: string explorerUrl: type: string addressUrl: type: string priority: type: number format: double kind: type: string chainId: type: number format: double nullable: true enabled: type: boolean shortNameV1: type: string required: - icon - addressValidation - tokenAddressValidation - id - created - name - shortName - explorerUrl - addressUrl - kind - enabled - shortNameV1 type: object additionalProperties: false TokenSecurityScan: properties: provider: type: string description: Screening provider that produced this verdict. resultType: $ref: '#/components/schemas/TokenScanResult' providerResultType: type: string description: >- The provider's own `result_type` string, kept unmapped so a verdict we don't model yet is still visible to support instead of being erased. maliciousScore: type: number format: double description: >- Provider `malicious_score`, 0..1. Arrives as a string; stored as a number. features: items: $ref: '#/components/schemas/TokenScanFeature' type: array default: [] unscannedReason: $ref: '#/components/schemas/TokenScanUnscannedReason' unscannedDetail: type: string description: >- Free-text detail behind `unscannedReason` (provider message, status…). scannedAt: type: string format: date-time expiresAt: type: string format: date-time description: When this verdict goes stale and the token should be re-scanned. required: - scannedAt - expiresAt type: object additionalProperties: false TokenScanResult: description: >- HS-1835 — normalized verdict for a swap-token security scan. Branch on this, never on individual `features` — the provider (Blockaid) already aggregates its features into the verdict, and the feature catalogue changes underneath us (ids get added, renamed and deprecated). `UNSCANNED` is the explicit fourth state the ticket calls for: provider outage, rate limit, timeout, unsupported chain, missing credentials or a verdict string we don't recognise. It always means *fail open* — an external scanner being unavailable must never block a swap. enum: - Benign - Warning - Malicious - Unscanned type: string TokenScanFeature: description: >- One provider feature. Stored verbatim, with **no allowlist** — Blockaid adds, renames and deprecates feature ids (INORGANIC_VOLUME is already deprecated), so hardcoding a subset goes stale. Reference/context for FE copy and admin visibility only. properties: featureId: type: string type: type: string description: >- Provider severity for this feature: Malicious | Warning | Benign | Info. description: type: string type: object additionalProperties: false TokenScanUnscannedReason: description: >- Why a token ended up `UNSCANNED`. Diagnostic only — never a branching input. enum: - NOT_CONFIGURED - UNSUPPORTED_CHAIN - NATIVE_TOKEN - RATE_LIMITED - TIMEOUT - PROVIDER_ERROR - NO_RESULT - SCAN_PENDING - NOT_A_TOKEN - UNKNOWN_RESULT_TYPE type: string securitySchemes: apiKey: type: apiKey name: Authorization in: header ````