> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a swap > Create a token swap. A swap exchanges one stablecoin for another between a source wallet and a destination wallet (owned by a user or an external wallet). The source and destination `currency` must be different. Provide exactly one of `source.amount` or `destination.amount` — the other side is derived from the quote. Provide exactly one of `destination.walletId` or `destination.externalWalletId`. Depending on the pricing model, the swap may be created directly or returned in an `OPEN_QUOTE` state that must be accepted before execution. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/swaps openapi: 3.0.0 info: title: Hifi API version: 3.0.0 description: API documentation for HIFI servers: - url: https://production.hifi.com description: Production server - url: https://sandbox.hifi.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Counter Party description: Counter party endpoints - name: Crypto Transfer description: Crypto transfer and batch transfer endpoints - name: Wallet description: Wallet and wallet offer endpoints - name: External Account description: External bank account endpoints (under a counter party) - name: External Wallet description: External wallet endpoints (under a counter party) - name: External Card description: External card endpoints (under a counter party) - name: Token Swap description: Token swap endpoints - name: Bridge description: Bridge endpoints - name: Virtual Account description: Virtual account endpoints - name: Compliance description: Compliance and compliance link endpoints - name: Webhook Endpoint description: Webhook endpoint endpoints - name: File description: File upload endpoints - name: Onramp description: Onramp (fiat to crypto) endpoints - name: Offramp description: Offramp (crypto to fiat) endpoints - name: Orchestration Address description: Orchestration (liquidation) address endpoints - name: KYC Link description: Hosted and custom KYC/KYB link endpoints - name: Transfer Approval description: Transfer approval endpoints - name: Corridor description: Supported fiat/crypto transfer corridor endpoints - name: Migration description: v2-to-v3 ID mapping endpoints paths: /v3/swaps: post: tags: - Token Swap summary: Create a swap description: > Create a token swap. A swap exchanges one stablecoin for another between a source wallet and a destination wallet (owned by a user or an external wallet). The source and destination `currency` must be different. Provide exactly one of `source.amount` or `destination.amount` — the other side is derived from the quote. Provide exactly one of `destination.walletId` or `destination.externalWalletId`. Depending on the pricing model, the swap may be created directly or returned in an `OPEN_QUOTE` state that must be accepted before execution. operationId: v3CreateSwap requestBody: $ref: '#/components/requestBodies/CreateSwapBody' responses: '200': $ref: '#/components/responses/CreateSwapResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: CreateSwapBody: required: true description: > Swap details. Source and destination currencies must differ, exactly one of `source.amount` / `destination.amount` must be provided, and exactly one of `destination.walletId` / `destination.externalWalletId` must be provided. content: application/json: schema: $ref: '#/components/schemas/SwapCreate' examples: UserWalletExample: summary: Swap into a user wallet (source amount) value: requestId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d source: walletId: wlt_3Kf9dQ2mNpXwZ7bV1aLcs currency: USDC amount: 100 destination: walletId: wlt_7bV1aLcs3Kf9dQ2mNpXwZ currency: USDT ExternalWalletExample: summary: Swap into an external wallet (destination amount) value: requestId: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e source: walletId: wlt_3Kf9dQ2mNpXwZ7bV1aLcs currency: USDC destination: externalWalletId: extw_9dQ2mNpXwZ7bV1aLcs3Kf currency: PYUSD amount: 250 responses: CreateSwapResponse: description: Swap created successfully. content: application/json: schema: $ref: '#/components/schemas/SwapObject' example: id: swap_7bV1aLcs3Kf9dQ2mNpXwZ requestId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d status: OPEN_QUOTE error: null errorDetails: null amount: '100' source: userId: usr_3Kf9dQ2mNpXwZ7bV1aLcs walletId: wlt_3Kf9dQ2mNpXwZ7bV1aLcs currency: USDC chain: POLYGON destination: userId: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: wlt_7bV1aLcs3Kf9dQ2mNpXwZ externalWalletId: null currency: USDT chain: POLYGON receipt: transactionHash: null quote: sendGross: amount: '100' currency: USDC sendNet: amount: '100' currency: USDC receiveGross: amount: '100' currency: USDT receiveNet: amount: '100' currency: USDT rate: '1.0' expiresAt: '2026-07-01T10:35:00.000Z' createdAt: '2026-07-01T10:30:00.000Z' updatedAt: '2026-07-01T10:30:00.000Z' BadRequestResponse: description: Bad Request — the request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: VALIDATION_ERROR message: One or more fields are invalid or missing. fields: - code: invalid_value message: Must be a valid email address field: email UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' ConflictResponse: description: >- Conflict — the request collides with the current state of the resource (e.g. idempotency-key reuse with a different payload). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: RESOURCE_CONFLICT message: Resource already exists or conflicts with current state InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: SwapCreate: type: object description: > Swap creation payload. Source and destination currencies must differ, exactly one of `source.amount` / `destination.amount` must be set, and exactly one of `destination.walletId` / `destination.externalWalletId` must be set. required: - requestId - source - destination properties: requestId: type: string format: uuid description: >- Client-generated idempotency key. A UUID unique to this swap request. example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d source: $ref: '#/components/schemas/SwapCreateSource' destination: $ref: '#/components/schemas/SwapCreateDestination' SwapObject: type: object description: A token swap. properties: id: type: string description: Public ID of the swap (prefixed with `swap_`). example: swap_7bV1aLcs3Kf9dQ2mNpXwZ requestId: type: string format: uuid description: Client-generated idempotency key supplied at creation. example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d status: type: string enum: - DRAFT - CREATED - PENDING - OPEN_QUOTE - QUOTE_FAILED - COMPLETED - FAILED example: OPEN_QUOTE error: type: string nullable: true description: User-facing error summary. Null unless the swap failed. example: null errorDetails: type: string nullable: true description: User-facing error details. Null unless the swap failed. example: null amount: type: string nullable: true description: Source amount of the swap. example: '100' source: $ref: '#/components/schemas/SwapSourceObject' destination: $ref: '#/components/schemas/SwapDestinationObject' receipt: $ref: '#/components/schemas/SwapReceipt' quote: $ref: '#/components/schemas/SwapQuote' createdAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' updatedAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' ApiError: type: object description: >- Standard v3 error shape, returned by validation failures and business-logic errors alike. properties: type: type: string description: >- Machine-readable error type, e.g. VALIDATION_ERROR, ACTION_NOT_ALLOWED, RESOURCE_CONFLICT. example: VALIDATION_ERROR message: type: string description: Human-readable error message. example: One or more fields are invalid or missing. fields: type: array description: >- Present on field-level validation errors. One entry per problem field. items: type: object properties: code: type: string description: Error code related to the field issue. message: type: string description: Error message for the specific issue. field: type: string description: The name of the field that has an issue. Unauthorized: type: object properties: type: type: string description: Unauthorized enum example: UNAUTHORIZED message: type: string description: Unauthorized message example: Authentication required InternalServerError: type: object properties: type: type: string example: INTERNAL_SERVER_ERROR description: Internal server error enum message: type: string example: An internal server error occurred description: Internal server error message SwapCreateSource: type: object description: Source of the swap. required: - walletId - currency properties: walletId: type: string description: Public ID of the source wallet (prefixed with `wlt_`). example: wlt_3Kf9dQ2mNpXwZ7bV1aLcs currency: type: string description: Source stablecoin. Sandbox does not support `USDT`. enum: - USDC - USDT - PYUSD0 - USDG - PYUSD example: USDC amount: type: number description: | Source amount to swap. Provide exactly one of `source.amount` or `destination.amount`. minimum: 1 maximum: 999999999 example: 100 SwapCreateDestination: type: object description: >- Destination of the swap. Provide exactly one of `walletId` or `externalWalletId`. required: - currency properties: walletId: type: string description: Public ID of the destination wallet (prefixed with `wlt_`). example: wlt_7bV1aLcs3Kf9dQ2mNpXwZ externalWalletId: type: string description: >- Public ID of the destination external wallet (prefixed with `extw_`). example: extw_9dQ2mNpXwZ7bV1aLcs3Kf currency: type: string description: >- Destination stablecoin. Must differ from the source currency. Sandbox does not support `USDT`. enum: - USDC - USDT - PYUSD0 - USDG - PYUSD example: USDT amount: type: number description: > Destination amount to receive. Provide exactly one of `source.amount` or `destination.amount`. minimum: 1 maximum: 999999999 example: 100 SwapSourceObject: type: object description: Resolved source of the swap. properties: userId: type: string description: Public ID of the source user (prefixed with `usr_`). example: usr_3Kf9dQ2mNpXwZ7bV1aLcs walletId: type: string description: Public ID of the source wallet (prefixed with `wlt_`). example: wlt_3Kf9dQ2mNpXwZ7bV1aLcs currency: type: string enum: - USDC - USDT - PYUSD0 - USDG - PYUSD example: USDC chain: type: string enum: - POLYGON - ETHEREUM - SOLANA - BASE - FLOW_EVM - BSC - TRON - CANTON example: POLYGON SwapDestinationObject: type: object description: Resolved destination of the swap. properties: userId: type: string description: Public ID of the destination user (prefixed with `usr_`). example: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: type: string description: >- Public ID of the destination wallet (prefixed with `wlt_`). Null when the destination is an external wallet. nullable: true example: wlt_7bV1aLcs3Kf9dQ2mNpXwZ externalWalletId: type: string description: >- Public ID of the destination external wallet (prefixed with `extw_`). Null when the destination is a user wallet. nullable: true example: null currency: type: string enum: - USDC - USDT - PYUSD0 - USDG - PYUSD example: USDT chain: type: string enum: - POLYGON - ETHEREUM - SOLANA - BASE - FLOW_EVM - BSC - TRON - CANTON example: POLYGON SwapReceipt: type: object description: On-chain receipt for the swap. properties: transactionHash: type: string nullable: true description: On-chain transaction hash of the completed swap. Null until settled. example: null SwapQuote: type: object nullable: true description: Commercial quote for the swap. Null until a quote has been generated. properties: sendGross: $ref: '#/components/schemas/SwapAmount' sendNet: $ref: '#/components/schemas/SwapAmount' receiveGross: $ref: '#/components/schemas/SwapAmount' receiveNet: $ref: '#/components/schemas/SwapAmount' rate: type: string description: Conversion rate from source to destination currency. example: '1.0' expiresAt: type: string format: date-time nullable: true example: '2026-07-01T10:35:00.000Z' SwapAmount: type: object description: An amount and its currency. properties: amount: type: string example: '100' currency: type: string enum: - USDC - USDT - PYUSD0 - USDG - PYUSD example: USDC securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````