VidepayDocumentation

Swap

Same-chain swaps convert assets on a single network, e.g. USDC to ETH on Base, without leaving Videpay. Quote fees, discover routes, create swaps with nested source/destination objects, and track progress via webhooks. Token diversification, but your backend stays in one repo.

Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.

When should I use this?

You hold USDC but need native ETH for gas on the same chain.
Treasury wants to convert USDC to another supported asset on one network.
You rebalance assets within a single chain balance.

Why use Videpay?

Nested CreateSwapDTO: source {chain, asset, amount}, destination {chain, asset, recipient, minimumAmountOut?}.
slippageBps and deadlineSeconds control execution bounds.
routing hints for DEX pool fee tiers.
flowType is same-chain in responses and webhooks.

USDC to ETH on Base Sepolia

Your hot wallet needs ETH for gas. You POST /swap with source and destination both on base, then receive swap.prepared → swap.initiated → swap.completed with the full swap object. Gas money acquired. Crisis averted.

Before you start

Sufficient merchant balance of source asset on the chain
Merchant registered on-chain
Webhook endpoint for swap lifecycle events

How same-chain swaps work

POST /swap/quote-fee with source and destination to preview fees.
GET /swap/routes to discover supported pairs.
POST /swap with CreateSwapDTO: Videpay routes via Uniswap V3.
swap.prepared when the record is created; swap.initiated on submission.
swap.completed or swap.failed when the on-chain transaction settles.
POST /swap/:id/sync to force reconciliation with a txHash.

Dashboard features

Dashboard → Swap

Select source and destination assets on the same chain, preview quotes, set slippage, and execute swaps with step-up auth. Swap history shows status, transaction hashes, and delivered amounts.

Quote fee before executing.
View route estimate and minimum amount out.
Monitor swap status and sync stale records.

Quote swap fee

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.

POST/swap/quote-fee

Preview protocol fee and route estimate. Accepts the same body as POST /swap.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "source": {03    "chain": "base",04    "asset": "USDC",05    "amount": "1000"06  },07  "destination": {08    "chain": "base",09    "asset": "ETH",10    "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",11    "minimumAmountOut": "0.45"12  },13  "slippageBps": 100,14  "deadlineSeconds": 900,15  "reference": "swap-usdc-eth-001",16  "routing": {17    "dexAdapterName": "UNISWAP_V3"18  }19}

List available routes

Field	Type	Required	Description
`businessId`	`uuid`	No	Target business. Omit when your API key is scoped to one business.
`chain`	`string`	No	Optional chain filter for routable pairs.

GET/swap/routes?chain=base

Discover supported swap pairs for your merchant chains.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Create a same-chain swap

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.

POST/swap

Execute a same-chain swap. source.chain and destination.chain must resolve to the same network. Emits swap.prepared.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "source": {03    "chain": "base",04    "asset": "USDC",05    "amount": "1000"06  },07  "destination": {08    "chain": "base",09    "asset": "ETH",10    "recipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",11    "minimumAmountOut": "0.45"12  },13  "slippageBps": 100,14  "deadlineSeconds": 900,15  "reference": "swap-usdc-eth-001",16  "routing": {17    "dexAdapterName": "UNISWAP_V3"18  }19}

GET/swap/swp_same_5c8d2e1f-9a3b-4c7d-8e6f-1a2b3c4d5e6f

Retrieve swap status and on-chain details.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

GET/swap?flowType=SAME_CHAIN&status=COMPLETED&limit=20

List swaps with filters.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

POST/swap/swp_same_5c8d2e1f-9a3b-4c7d-8e6f-1a2b3c4d5e6f/sync

Force sync with on-chain state using a txHash.

Headers

headers

01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json

Request body

request.json

01{02  "txHash": "0xsourceSwapTx..."03}

Swap object reference

Field	Type	Required	Description
`id / reference`	`uuid / string`	No	Swap record ID and your reconciliation reference.
`flowType`	`enum`	No	same-chain or cross-chain.
`status`	`enum`	No	prepared, initiated, completed, or failed.
`source / destination`	`object`	No	Chain, asset, amounts, txHash, and recipient details per leg.
`routing`	`object`	No	DEX and bridge adapter used (type, dex, bridge).
`quote`	`object`	No	feeBps and priceImpactBps at creation time.

Webhooks you'll receive

Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.

Webhookswap.prepared

Sent when a swap record is created and ready for execution.

Delivery headers

webhook-headers

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...

Webhookswap.updated

Sent when swap progress changes before terminal status.

Delivery headers

webhook-headers

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...

Webhookswap.completed

Sent when a same-chain swap finishes successfully.

Delivery headers

webhook-headers

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...

Webhookswap.failed

Sent when a swap fails after initiation.

Delivery headers

webhook-headers

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...

← Escrow Cross-chain swap →