> ## Documentation Index > Fetch the complete documentation index at: https://docs.onswitch.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Initiate > Initiate a swap transaction between two stablecoin assets. ## OpenAPI ````yaml /openapi.json post /swap/initiate openapi: 3.0.3 info: title: Receive stablecoin. Get fiat in seconds. description: Stablecoin collection and settlement layer. version: 1.0.0 contact: name: Switch Labs email: contact@onswitch.xyz license: name: Proprietary x-tagGroups: - name: Institution tags: - Institution - name: Miscellaneous tags: - Miscellaneous - name: History tags: - History - name: Payment tags: - Payment - name: Webhook tags: - Webhook - name: Offramp tags: - Offramp - name: Onramp tags: - Onramp - name: Swap tags: - Swap - name: Developer tags: - Developer - name: Wallet tags: - Wallet - name: Compliance tags: - Compliance servers: - url: https://api.onswitch.xyz description: Production server security: [] tags: - name: Institution description: Institution discovery and bank or payment-rail lookup - name: Miscellaneous description: Requirements, coverage, assets, confirmation, and transaction status - name: History description: Payment history and summaries for the partner's account - name: Payment description: Saved payment beneficiaries, payment confirmation, and status - name: Webhook description: Webhook delivery history and callback resend - name: Offramp description: Offramp transaction endpoints for converting stablecoins to local currency - name: Onramp description: Onramp transaction endpoints for converting local currency to stablecoins - name: Swap description: Swap endpoints for exchanging between different stablecoin assets - name: Developer description: Developer fee balance and withdrawal - name: Wallet description: >- Wallet endpoints for creating and managing chain abstracted stablecoin wallets - name: Compliance description: AML compliance screening for PEP, sanctions, and other regulatory reasons paths: /swap/initiate: post: tags: - Swap summary: Initiate description: Initiate a swap transaction between two stablecoin assets. operationId: initiateSwap requestBody: required: true content: application/json: schema: type: object required: - amount - from_asset - to_asset - beneficiary properties: amount: type: number minimum: 0 from_asset: $ref: '#/components/schemas/AssetCode' to_asset: $ref: '#/components/schemas/AssetCode' beneficiary: description: The recipient of the swap transaction. oneOf: - $ref: '#/components/schemas/InitiateSwapBeneficiaryById' - $ref: '#/components/schemas/InitiateSwapBeneficiaryByWallet' - $ref: '#/components/schemas/InitiateSwapBeneficiaryByAddress' exact_output: type: boolean default: false callback_url: type: string format: uri description: Webhook URL to receive transaction status updates. reference: type: string format: uuid developer_fee: type: number description: Optional developer fee percentage (0-100) minimum: 0 maximum: 100 developer_recipient: type: string description: Optional wallet address to receive developer fee. refund_address: type: string description: >- Optional wallet address to receive refunds for failed/expired deposits. The refund address must be on the same blockchain specified for the payment. example: amount: 100 from_asset: base:usdc to_asset: solana:usdt beneficiary: wallet_address: '0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a' exact_output: false callback_url: https://your-app.com/webhook reference: a3f9c2e1-7b4d-4a8e-9c62-1d8f4e6b2a90 developer_fee: 0.5 developer_recipient: '0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a' refund_address: '0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a' responses: '200': description: Successfully initiated swap transaction content: application/json: schema: type: object required: - success - message - timestamp - data properties: success: type: boolean message: type: string timestamp: type: string format: date-time data: description: Response data type: object nullable: true required: - status - type - reference - rate - fee - source - destination - deposit properties: status: type: string enum: - AWAITING_DEPOSIT - PROCESSING - COMPLETED - FAILED type: type: string enum: - SWAP reference: type: string format: uuid rate: type: number fee: type: object required: - total - platform - developer - currency properties: total: type: number platform: type: number developer: type: number currency: type: string source: type: object required: - amount - currency properties: amount: type: number currency: type: string destination: type: object required: - amount - currency properties: amount: type: number currency: type: string deposit: type: object required: - amount - address - asset - note properties: amount: type: number address: type: string asset: $ref: '#/components/schemas/AssetCode' note: type: array items: type: string example: success: true message: Swap initiated successfully timestamp: '2026-04-18T14:22:08.631Z' data: status: AWAITING_DEPOSIT type: SWAP reference: a3f9c2e1-7b4d-4a8e-9c62-1d8f4e6b2a90 rate: 1 fee: total: 0.5 platform: 0.45 developer: 0.05 currency: USDC source: amount: 100 currency: USDC destination: amount: 99.5 currency: USDT deposit: amount: 100 address: '0x8F3aC91d2B741E59f064E9053a4d2E8F1c0b6D93a' asset: base:usdc note: - >- Kindly send the exact amount to the wallet address to complete the transaction. - >- This dynamic wallet address has a 30 minutes expiry window and can only be used once. '400': $ref: '#/components/responses/BadRequest' security: - ServiceKey: [] components: schemas: AssetCode: type: string enum: - base:usdc - solana:usdc - solana:usdt - ethereum:usdc - ethereum:usdt - polygon:usdc - polygon:usdt - bsc:usdc - bsc:usdt - arbitrum:usdc - optimism:usdc - gnosis:usdc - gnosis:usdt - arbitrum:usdt - avalanche:usdc - monad:usdc - optimism:usdt - monad:usdt - plasma:usdt - avalanche:usdt - tron:usdt - linea:usdt - mantle:usdt - hyperevm:usdt - berachain:usdt - linea:usdc - berachain:usdc - sonic:usdc - base:cngn - bsc:cngn InitiateSwapBeneficiaryById: title: Receive to saved beneficiary type: object required: - id description: Reuse a saved beneficiary from **GET /payment/beneficiary**. properties: id: $ref: '#/components/schemas/BeneficiaryObjectId' additionalProperties: true InitiateSwapBeneficiaryByWallet: title: Receive to Switch wallet type: object required: - wallet description: Receive stablecoins to existing Switch wallet. properties: wallet: type: string description: Internal switch wallet `id` additionalProperties: true InitiateSwapBeneficiaryByAddress: title: Receive to external wallet type: object required: - wallet_address description: New beneficiary details. properties: wallet_address: type: string additionalProperties: true BeneficiaryObjectId: type: string pattern: ^[a-f0-9]{24}$ description: Unique identifier for the beneficiary responses: BadRequest: description: Bad request - Invalid input parameters or validation error content: application/json: schema: type: object required: - success - message - timestamp properties: success: type: boolean example: false message: type: string description: Error message describing what went wrong timestamp: type: string format: date-time data: description: Additional error details nullable: true example: success: false message: amount must be greater than 0 for the selected corridor timestamp: '2026-04-18T14:22:08.631Z' data: null securitySchemes: ServiceKey: type: apiKey in: header name: x-service-key description: Service key for API authentication ````