Skip to main content

Documentation Index

Fetch the complete documentation index at: https://coinvoyage-3c99945b.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

CoinVoyage handles the full complexity of cross-chain payments so you don’t have to. When a user pays, CoinVoyage scans their wallet, fetches quotes from multiple liquidity providers, selects the optimal route, and executes each step in sequence — all the way through to settlement at your destination address. The sections below walk through every stage of that process.

​
End-to-end payment flow

The sequence diagram below shows every actor and message involved in a complete payment:

​
Detailed flow steps

1

PayOrder creation

Your server (or the SDK’s ApiClient) creates a PayOrder specifying the destination chain, asset, and amount. CoinVoyage returns a PayOrder ID and immediately fires a payorder_created webhook. You then pass that ID to the payment modal so the user can begin.Three modes are available depending on your use case — Deposit, Sale, and Refund — each described in detail on the Pay orders page.
const payOrder = await apiClient.createDepositPayOrder({
  intent: {
    asset: {
      chain_id: ChainId.SUI,
      address: null, // null = native token (SUI)
    },
    amount: {
      token_amount: 10, // 10 SUI
    },
    receiving_address: "0xYourWalletAddress",
  },
});
2

Payment method selection

The user opens the payment modal and picks their preferred chain and token. CoinVoyage supports payment from:
  • SUI — Sui blockchain
  • BTC — Bitcoin
  • SOL — Solana
  • EVM — Ethereum, Arbitrum, Base, Optimism, Polygon, BSC, and more
Once the user selects a chain, they provide their wallet address so CoinVoyage can scan for available balances.
3

Quote generation

CoinVoyage builds quotes by:
  1. Scanning wallet balances to identify tokens the user can pay with
  2. Querying providers for live rates — AMMs (Uniswap, Jupiter, Cetus), CCTP for cross-chain USDC, ChangeNow for cross-chain exchanges, and direct same-chain transfers
  3. Optimizing routes by chaining providers together when that yields a better rate
  4. Ranking quotes by best effective output (highest received amount, lowest fees)
The top quotes are surfaced to the user for selection.
4

Quote selection and payment details

After the user picks a quote, CoinVoyage generates the exact payment instructions for that route:
  • Deposit address — a unique address generated for this payment
  • Exact amount — the precise token amount to send
  • Expiration time — the payment window, typically 30 minutes
  • Refund address — where funds return if anything goes wrong
A quote looks like this before the user confirms:
Pay:            0.05 ETH (Ethereum)
Receive:        10 SUI (Sui Network)
Route:          Ethereum → CCTP → Sui
Fee:            1.5%
Estimated time: ~30 seconds
5

User payment

The user sends the exact amount to the deposit address from their wallet. CoinVoyage monitors the blockchain for:
  • Transaction submission — the payment has been broadcast
  • On-chain confirmation — the transaction is included in a block
  • Amount verification — the correct amount was received
Your server receives a payorder_confirming webhook as soon as the transaction is detected.
6

Backend execution

Once payment is confirmed, CoinVoyage executes the selected route. Routes can involve a single provider or a chain of providers:Single-provider flow
User Payment → Provider → Destination
Example: SOL → Direct Transfer → SOL (same chain)
Multi-provider chain
User Payment → Provider 1 → Provider 2 → Destination
Example: ETH → Uniswap (ETH → USDC) → CCTP → SUI
CoinVoyage handles route execution, error recovery, and real-time status webhooks throughout this stage. If any step fails, an automatic refund is initiated.
Webhook subscriptions are configured with uppercase ORDER_* identifiers (e.g., ORDER_EXECUTING), but the delivered JSON payload uses lowercase payorder_* values in the type field (e.g., payorder_executing).
7

Settlement and completion

When funds arrive at the destination address, CoinVoyage marks the PayOrder as COMPLETED and fires the payorder_completed webhook. All relevant transaction hashes are recorded on-chain.If execution fails at any point:
  1. An automatic refund is initiated
  2. Funds are returned to the user’s refund address
  3. The PayOrder status changes to REFUNDED
  4. A payorder_refunded webhook is fired

​
Provider chaining example

CoinVoyage can chain multiple providers together to find the best possible route for a given payment. Here is what that looks like when a user pays with ETH on Ethereum and you want to receive SUI: 
Step 1: User pays ETH on Ethereum
   |
Step 2: Uniswap swaps ETH → USDC (on Ethereum)
   |
Step 3: CCTP transfers USDC from Ethereum → Sui
   |
Step 4: Sui DEX swaps USDC → SUI
   |
Step 5: SUI delivered to your wallet
The entire process is:
  • Automated — no manual intervention required at any step
  • Optimized — the best route is calculated in real time before the user confirms
  • Transparent — all fees, routes, and timing are shown to the user upfront
  • Fast — typically completes in under 60 seconds