Same-Chain Swaps - deBridge Home

A product surface wants single-network token conversions that behave like reliable transactions, not optimistic quotes. The integration path is intentionally compact: first, ask for a quote; then, once the sender and recipient are known, request the fully constructed transaction. Under the hood, DLN simulates routes across multiple aggregators and returns calldata that targets DeBridgeRouter on EVM, or a serialized transaction on Solana. The result is an estimation-then-execution loop that stays responsive and grounded in market reality, with the added benefit of adaptive slippage that takes real-time conditions into account.

What this guide covers

Endpoints and request shapes to obtain quotes and ready-to-send transactions.
EVM and Solana submission flows based on the provided TypeScript examples.
Where affiliate fee parameters plug into the flow.
Tracking and observability via the Stats API for histories and per-swap lookups.
Freshness and slippage guidance for resilient UX at scale.

Reference: DLN OpenAPI specification. Reference: Stats API for order tracking.

Architecture in brief

A same-chain swap never leaves its origin network. The DLN API handles route discovery and simulation, returning:

EVM: tx with to, data, and (when required) value, crafted to call DeBridgeRouter.
Solana: tx.data containing a hex-encoded VersionedTransaction that is deserialized, updated with a recent blockhash, signed, and sent.

This design keeps the UI responsive before a wallet is connected, and returns an executable payload once sender and recipient are known.

Endpoints

Get a quote (estimation)

Use GET /v1.0/chain/estimation to retrieve a quote for the desired pair. This step is suitable when the wallet is not connected or recipient is not yet known. Minimal request - SOL for USDC on Solana

{
  "chainId": "7565164",
  "tokenIn": "11111111111111111111111111111111", // SOL on Solana
  "tokenInAmount": "200000",
  "tokenOut": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC on Solana,
  "slippage": "auto" // Default value
}

The response contains pricing, route details, aggregator comparison, and costs metadata used to inform UI and future submission.
The recommended value for slippage parameter is auto. The API selects a minimum reasonable slippage band from live market conditions and simulations.

Full response schema

{
  "estimation": {
    "tokenIn": {
      "address": "string", // token address
      "name": "string", // token name
      "symbol": "string", // token symbol
      "decimals": 0, // token decimals
      "amount": "string", // input amount
      "approximateUsdValue": 0 // approximate USD value of input amount
    },
    "tokenOut": {
      "address": "string", // token address
      "name": "string", // token name
      "symbol": "string", // token symbol
      "decimals": 0, // token decimals
      "amount": "string", // output amount
      "minAmount": "string", // minimum output amount
      "approximateUsdValue": 0 // approximate USD value of output amount
    },
    "slippage": 0, // slippage percentage (e.g. 0.5 for 0.5%)
    "recommendedSlippage": 0, // recommended slippage percentage based on route simulation and volatility
    "protocolFee": "string", // protocol fee amount in tokenIn
    "estimatedTransactionFee": { // estimated transaction fee details
      "total": "string",
      "details": {
        "giveOrderState": "string",
        "giveOrderWallet": "string",
        "nonceMaster": "string",
        "txFee": "string",
        "priorityFee": "string",
        "gasLimit": "string",
        "gasPrice": "string",
        "baseFee": "string",
        "maxFeePerGas": "string",
        "maxPriorityFeePerGas": "string"
      },
      "approximateUsdValue": 0 // approximate USD value of the total estimated transaction fee
    },
    "costsDetails": [ // Breakdown of costs and fees
      {
        "chain": "string",
        "tokenIn": "string",
        "tokenOut": "string",
        "amountIn": "string",
        "amountOut": "string",
        "type": "string",
        "payload": {
          "feeAmount": "string",
          "feeBps": "string",
          "amountOutBeforeCorrection": "string",
          "estimatedVolatilityBps": "string",
          "actualFeeAmount": "string",
          "actualFeeBps": "string",
          "subsidyAmount": "string",
          "feeApproximateUsdValue": "string"
        }
      }
    ],
    "comparedAggregators": [ // List of queried aggregators and their rates
      {
        "name": "string",
        "amount": "string",
        "approximateUsdValue": 0,
        "priceDrop": 0,
        "imageUrl": "string"
      }
    ]
  }
}

Get an executable transaction

Use GET /v1.0/chain/transaction to obtain the same quote fields plus a tx object ready to be signed and broadcast. Minimal request - USDC for MATIC on Polygon

{
  "chainId": "137",
  "tokenIn": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
  "tokenInAmount": "200000",
  "tokenOut": "0x0000000000000000000000000000000000000000", // Native token (MATIC on Polygon)
  "tokenOutRecipient": "<recipient_address>",
  "senderAddress": "<sender_address>",
  "slippage": "auto" // Default value
}

Response Highlights

{
  /* same content as in /estimation */
  "tx": {
    "to": "<DeBridgeRouter_target_on_evm>",
    "data": "0x...",
    "value": "0x..."
  }
}

On Solana, the tx object contains only:

{
  /* same content as in /estimation */
  "tx": { "data": "0x<hex_versioned_transaction>" }
}

Compared Aggregators

DLN’s same-chain swaps leverage multiple DeFi aggregators to ensure competitive pricing and route diversity. Response payload for both estimation and transaction endpoints includes the comparedAggregators field, which lists the aggregators queried during route discovery. This transparency allows integrators to understand the aggregator choice and provides insights into the liquidity sources considered for the swap.

EVM submission flow

The EVM submission sequence mirrors a typical ERC-20 flow plus a single call to DeBridgeRouter:

Fetch estimation with /v1.0/chain/estimation to present the quote.
Request transaction and quote via /v1.0/chain/transaction once the sender and recipient are known.
Ensure allowance for tokenIn toward tx.to - the DeBridgeRouter contract. Deployed contracts page should be consulted for the correct address.
Send the main transaction using the returned tx object.

Skeleton (TypeScript) aligning with the provided example

// Pseudocode stitched to the structure of the provided EVM example
const swap = await createDeBridgeSameChainSwap({
  chainId: "137", // Polygon chainId
  tokenIn: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC on Polygon
  tokenInAmount: "200000",
  tokenOut: "0x0000000000000000000000000000000000000000", // Native token (MATIC on Polygon)
  tokenOutRecipient: senderAddress,
  senderAddress
});

// 1) Validate response
const tx = swap?.tx;
if (!tx?.to || !tx?.data) throw new Error("Invalid tx");

// 2) Approve if needed - only for ERC-20 tokenIn
const required = BigInt(swap.tokenIn.amount);
const currentAllowance = await erc20.allowance(senderAddress, tx.to);
if (currentAllowance < required) {
  const approveTx = await erc20.approve(tx.to, required);
  await approveTx.wait();
}

// 3) Submit the transaction
const sent = await signer.sendTransaction(tx);
const receipt = await sent.wait();

Complete EVM example

The full, production-ready script (logging, receipt checks, explorer links) is available here and can be reused for inspiration in real integrations.

Solana submission flow

The Solana variant returns a serialized VersionedTransaction ready to be deserialized, refreshed, signed, and sent:

Request transaction and quote via /v1.0/chain/transaction with Solana chain id.
Deserialize the hex tx.data into a VersionedTransaction.
Refresh blockhash with getLatestBlockhash() and set tx.message.recentBlockhash.
- Optionally, adjust CU price/limit using a helper (as in the provided example).
Sign and send the raw transaction, then confirm.

Skeleton (TypeScript) aligning with the provided Solana example

const swap = await createDeBridgeSameChainSwap({
  chainId: "7565164", // Solana chainId
  tokenIn: "11111111111111111111111111111111", // SOL on Solana
  tokenInAmount: "200000",
  tokenOut: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC on Solana
  tokenOutRecipient: solWallet.publicKey.toBase58(),
  senderAddress: solWallet.publicKey.toBase58()
});

// Deserialize hex-encoded VersionedTransaction
const tx = VersionedTransaction.deserialize(Buffer.from(swap.tx.data.slice(2), "hex"));

// Refresh blockhash and (optionally) adjust CU price/limit, then sign
const { blockhash } = await connection.getLatestBlockhash();
tx.message.recentBlockhash = blockhash;
// updatePriorityFee(tx, NEW_CU_PRICE, NEW_CU_LIMIT); // as in the github example
tx.sign([solWallet]);

// Send and confirm
const sig = await connection.sendRawTransaction(tx.serialize(), { skipPreflight: false });

Complete Solana example

The full script (simulation, CU sizing, prioritization fee median, and final submission) is available here and can be reused for inspiration in real integrations.

Affiliate fees

Affiliate fees are supported in the same-chain flow. The parameters used are affiliateFeePercent and affiliateFeeRecipient. More details are available in the the Same-Chain Affiliate Fees article.

The higher the affiliate fee, the worse rates the users using the app will get.

Tracking and observability

Tracking is performed with the Stats API. The default order history endpoints now include same-chain swaps when requested explicitly.

Wallet histories (filtered list)

For listing same-chain swaps of a single wallet POST https://dln-api.debridge.finance/api/Orders/filteredList should be used with a filterMode: "SameChain" parameter.`: Allowed values for filterMode are:

"CrossChain" (default)
"SameChain"
"Mixed"

Example request

{ "skip": 0, "take": 1, "maker": "<wallet_address>", "filterMode": "SameChain" }

Example response

{
  "orders": [
    {
      "orderId": { /* order ID object - with bytes, bytes array and string values */ },
      "creationTimestamp": 1759141461, // Unix timestamp
      "giveOfferWithMetadata": {
        "chainId": { /* chain ID object with different representations */ },
        "tokenAddress": { /* token address object - with different representations */ },
        "amount": { /* amount object - with different representations */ },
        "metadata": { /* input token metadata */
          "decimals": 6,
          "name": "Dephaser JPY",
          "symbol": "JPYT",
          "logoURI": null
        },
        "decimals": 6,
        "name": "Dephaser JPY",
        "symbol": "JPYT",
        "logoURI": null
      },
      "takeOfferWithMetadata": {
        "chainId": { /* chain ID object with different representations */ },
        "tokenAddress": { /* token address object - with different representations */ },
        "amount": { /* amount object - with different representations */ },
        "metadata": { /* output token metadata */
          "decimals": 18,
          "name": "AntHive",
          "symbol": "ANTH",
          "logoURI": null
        },
        "decimals": 18,
        "name": "AntHive",
        "symbol": "ANTH",
        "logoURI": null
      },
      "state": "Fulfilled", // Swap state
      "affiliateFee": {
        "beneficiarySrc": { /* affiliate fee beneficiary address object - with bytes, bytes array and string values */ },
        "amount": { /* amount object - with bytes, bytes array and string values */ }
      },
      "createEventTransactionHash": { /* transaction hash object - with bytes, bytes array and string values */ },
      "tradeType": "SameChain"
    }
  ],
  "totalCount": 24
}

Same-chain swaps do not create an on-chain DLN order entity. The Stats API maps same-chain data into an order-like representation purely for consistency in histories and dashboards.

Single order lookup

To get details of a single order from the transaction hash, GET https://dln-api.debridge.finance/api/SameChainSwap/${chainId}/tx/${transactionHash} should be used with chainId and transactionHash parameters. Response structure is identical to the order object in the filtered list.

Freshness and slippage

Quotes are tied to current market conditions and route simulations. Signing and submission should occur shortly after a transaction payload is received; stale quotes should be refreshed every 30 seconds. The recommended value for slippage parameter is "auto". The API selects a minimum reasonable slippage bound based on volatility and route simulation, a design that reduces execution risk without forcing conservative hard-coding.

Example links

Production checklist

Fetch the estimation endpoint for quotes before the wallet is connected; request the transaction endpoint for quotes and a transaction object once senderAddress and tokenOutRecipient are known.
Prefer adaptive slippage with auto.
On EVM, ensure tokenIn allowance toward the DeBridgeRouter target in tx.to.
Refresh quotes every 30 seconds if signing is delayed to avoid staleness.
Use Stats API filterList endpoint with filterMode: "SameChain" for observability.

Documentation Index

​What this guide covers

​Architecture in brief

​Endpoints

​Get a quote (estimation)

​Get an executable transaction

​Compared Aggregators

​EVM submission flow

​Complete EVM example

​Solana submission flow

​Complete Solana example

​Affiliate fees

​Tracking and observability

​Wallet histories (filtered list)

​Single order lookup

​Freshness and slippage

​Example links

​Production checklist

What this guide covers

Architecture in brief

Endpoints

Get a quote (estimation)

Get an executable transaction

Compared Aggregators

EVM submission flow

Complete EVM example

Solana submission flow

Complete Solana example

Affiliate fees

Tracking and observability

Wallet histories (filtered list)

Single order lookup

Freshness and slippage

Example links

Production checklist