Cross-chain swaps move assets between Videpay networks: e.g. consolidate Polygon Amoy revenue to Base Sepolia treasury. Use the same CreateSwapDTO with different source.chain and destination.chain; flowType becomes cross-chain and bridgeAsset fields appear in responses. Multichain treasury ops without opening twelve tabs.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
Customers pay on Polygon Amoy but your treasury is on Base Sepolia. You POST /swap with source.chain base and destination.chain polygon (or vice versa). swap.initiated fires on the source chain; swap.completed includes bridge metadata. Chain-hopping, documented.
Dashboard → Cross-chain swap
Pick source and destination chains, preview bridge fees and estimated delivery, set minimumAmountOut for slippage protection, and monitor bridge progress from the swap detail view.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
source.chain | string | Yes | Source chain (e.g. base, polygon). Sandbox resolves to testnets. |
source.asset | string | Yes | Asset symbol or on-chain token address to sell. |
source.amount | decimal string | Yes | Human-readable amount to swap from merchant balance. |
destination.chain | string | Yes | Destination chain. Same as source.chain for same-chain swaps. |
destination.asset | string | Yes | Asset symbol or address to receive. |
destination.recipient | address | Yes | Wallet that receives the output asset. |
destination.minimumAmountOut | decimal string | No | Optional floor for destination amount. Recommended to protect against slippage. |
slippageBps | integer | No | Slippage tolerance in basis points (1–5000). Default 100. |
deadlineSeconds | integer | No | Swap validity window in seconds (60–86400). Default 900. |
reference | string | No | Your reconciliation reference (max 120). |
metadata | object | No | Arbitrary JSON stored on the swap record. |
routing.bridgeAsset | string | No | Cross-chain only: bridge asset override. Omit for auto-routing. |
routing.dexAdapterName | string | No | DEX adapter override (e.g. UNISWAP_V3). Default: auto. |
routing.bridgeAdapterName | string | No | Bridge adapter override (e.g. STARGATE). Default: auto. |
routing.sameChainPoolFeeBps | integer | No | Same-chain Uniswap V3 pool fee tier override in bps. |
routing.sourcePoolFeeBps | integer | No | Cross-chain source-side pool fee override in bps. |
routing.destinationPoolFeeBps | integer | No | Cross-chain destination-side pool fee override in bps. |
routing.bridgeData | hex string | No | Raw bridge adapter bytes payload. Defaults to 0x. |
/swap/quote-feeQuote fees and bridge estimate for a cross-chain swap.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "source": {03 "chain": "base",04 "asset": "USDC",05 "amount": "5000"06 },07 "destination": {08 "chain": "polygon",09 "asset": "USDC",10 "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",11 "minimumAmountOut": "4950"12 },13 "slippageBps": 50,14 "deadlineSeconds": 1800,15 "reference": "swap-base-polygon-001",16 "routing": {17 "bridgeAsset": "USDC",18 "bridgeAdapterName": "STARGATE"19 }20}| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
source.chain | string | Yes | Source chain (e.g. base, polygon). Sandbox resolves to testnets. |
source.asset | string | Yes | Asset symbol or on-chain token address to sell. |
source.amount | decimal string | Yes | Human-readable amount to swap from merchant balance. |
destination.chain | string | Yes | Destination chain. Same as source.chain for same-chain swaps. |
destination.asset | string | Yes | Asset symbol or address to receive. |
destination.recipient | address | Yes | Wallet that receives the output asset. |
destination.minimumAmountOut | decimal string | No | Optional floor for destination amount. Recommended to protect against slippage. |
slippageBps | integer | No | Slippage tolerance in basis points (1–5000). Default 100. |
deadlineSeconds | integer | No | Swap validity window in seconds (60–86400). Default 900. |
reference | string | No | Your reconciliation reference (max 120). |
metadata | object | No | Arbitrary JSON stored on the swap record. |
routing.bridgeAsset | string | No | Cross-chain only: bridge asset override. Omit for auto-routing. |
routing.dexAdapterName | string | No | DEX adapter override (e.g. UNISWAP_V3). Default: auto. |
routing.bridgeAdapterName | string | No | Bridge adapter override (e.g. STARGATE). Default: auto. |
routing.sameChainPoolFeeBps | integer | No | Same-chain Uniswap V3 pool fee tier override in bps. |
routing.sourcePoolFeeBps | integer | No | Cross-chain source-side pool fee override in bps. |
routing.destinationPoolFeeBps | integer | No | Cross-chain destination-side pool fee override in bps. |
routing.bridgeData | hex string | No | Raw bridge adapter bytes payload. Defaults to 0x. |
/swapExecute a cross-chain swap. source.chain and destination.chain must differ. Emits swap.prepared.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "source": {03 "chain": "base",04 "asset": "USDC",05 "amount": "5000"06 },07 "destination": {08 "chain": "polygon",09 "asset": "USDC",10 "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",11 "minimumAmountOut": "4950"12 },13 "slippageBps": 50,14 "deadlineSeconds": 1800,15 "reference": "swap-base-polygon-001",16 "routing": {17 "bridgeAsset": "USDC",18 "bridgeAdapterName": "STARGATE"19 }20}/swap/swp_xchain_5c8d2e1f-9a3b-4c7d-8e6f-1a2b3c4d5e6fRetrieve cross-chain swap with bridge metadata.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json/swap/swp_xchain_5c8d2e1f-9a3b-4c7d-8e6f-1a2b3c4d5e6f/syncSync cross-chain swap state from source or bridge txHash.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "txHash": "0xsourceSwapTx..."03}Optional routing object on CreateSwapDTO lets you override bridge and DEX adapters. Omit for backend auto-routing.
| Field | Type | Required | Description |
|---|---|---|---|
routing.bridgeAsset | string | No | Cross-chain only: bridge asset override. Omit for auto-routing. |
routing.dexAdapterName | string | No | DEX adapter override (e.g. UNISWAP_V3). Default: auto. |
routing.bridgeAdapterName | string | No | Bridge adapter override (e.g. STARGATE). Default: auto. |
routing.sameChainPoolFeeBps | integer | No | Same-chain Uniswap V3 pool fee tier override in bps. |
routing.sourcePoolFeeBps | integer | No | Cross-chain source-side pool fee override in bps. |
routing.destinationPoolFeeBps | integer | No | Cross-chain destination-side pool fee override in bps. |
routing.bridgeData | hex string | No | Raw bridge adapter bytes payload. Defaults to 0x. |
| Field | Type | Required | Description |
|---|---|---|---|
bridgeAsset | object | No | Intermediate asset used for bridging (usually USDC). |
bridgeEstimate | object | No | amount / amountRaw expected across the bridge. |
source.messageId | string | No | Bridge message identifier on cross-chain swaps. |
destination.deliveredAmount | string | No | Actual amount received on destination chain. |
Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
swap.preparedSent when a swap record is created and ready for execution.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: swap.prepared04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...swap.initiatedSent when the swap transaction is submitted on the source chain.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: swap.initiated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...swap.completedSent when a cross-chain swap finishes successfully.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: swap.completed04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...swap.updatedSent when swap progress changes before terminal status.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: swap.updated04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...swap.failedSent when a swap fails after initiation.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: swap.failed04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...