Swap

A swap converts stablecoins between chains or token types (e.g. USDC on Base to USDT on Polygon) using Celar's bridging infrastructure. Swaps run on mainnet only.

Swaps are available on mainnet only. Sandbox does not support this operation type. Use base, polygon, arbitrum, or ethereum as chain values.

How it works

1. Submit a swap request specifying the source token/chain and destination token/chain
2. Celar routes the swap through its settlement layer (via Relay)
3. Response returns an on-chain hash of the deposit transaction
4. Tokens are delivered to the customer's Celar wallet on the destination chain, or to the provided destination.address

Prerequisites

• A valid customer_id: see Register a Customer
• A funded Celar wallet (walletId) holding the source token
• A unique Idempotency-Key for the request

Request

curl --request POST \
  --url https://api.celar.io/api/v1/payments/transfer \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique_uuid>' \
  --data '{
    "operationType": "swap",
    "customer_id": "cr_2ae76bc76f03437d",
    "amount": 100,
    "source": {
      "currency": "USDC",
      "chain": "base",
      "walletId": "cw_1053b738d73ad9b5"
    },
    "destination": {
      "currency": "USDT",
      "chain": "polygon",
      "address": "0xabc123def456abc123def456abc123def456abc1"
    }
  }'

info

destination.address is optional. If omitted, swapped tokens are delivered to the customer's Celar wallet on the destination chain.

Response

{
  "message": "Request successful",
  "hash": "0x4c5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
}

Field	Required	Description
message		Confirmation that the swap was initiated
hash		On-chain transaction hash of the deposit submitted to Relay

Field reference

Field	Required	Description
operationType	Yes	swap
customer_id	Yes	The customer whose wallet is being used
amount	Yes	Amount of the source token to swap
source.currency	Yes	USDC or USDT
source.chain	Yes	base, polygon, arbitrum, or ethereum
source.walletId	Yes	Celar wallet ID holding the source token
destination.currency	Yes	USDC or USDT
destination.chain	Yes	base, polygon, arbitrum, or ethereum
destination.address	No	External address to deliver swapped tokens to

Supported swap routes

Any combination of the following is supported:

Field	Required	Description
USDC		base, polygon, arbitrum, ethereum
USDT		base, polygon, arbitrum, ethereum

Notes

• Swaps are not available on baseSepolia or any testnet environment
• Same-chain, same-token swaps (e.g. USDC Base to USDC Base) are not valid
• Settlement time depends on bridge and chain congestion: monitor via webhooks

See Payment Statuses and Webhooks for more.