Swap Token - Integration Guide

This guide explains how to implement token swaps in your application. The process includes: requesting a quote, then executing the swap via the SWAP_FROM_QUOTE operation.

1. Get a Quote

Before executing a swap, you must obtain a quote that indicates the amount of tokens you will receive in exchange, as well as the associated fees.

Endpoint : GET /v1.2/safes/swap/quote

Headers :

• Authorization: Bearer <access_token> (required)

Query Parameters :

• sellTokenAddress (string, required) : Address of the token to sell (0x... format)
• buyTokenAddress (string, required) : Address of the token to buy (0x... format)
• amount (string, required) : Amount to sell in human-readable decimal format (e.g., "10.50")
• chainId (number, optional) : Target chain ID. If omitted, uses the effective chain (X-Blockchain-Id or default chain)
• safeAddress (string, optional) : Safe address to use as receiver. If omitted, uses the first Safe of the authenticated user
• provider (string, optional) : Provider to use. Possible values: "COWSWAP", "1INCH", "BOTH" (default: "BOTH")

Request Example :

GET /v1.2/safes/swap/quote?sellTokenAddress=0xcb444e90d8198415266c6a2724b7900fb12fc56e&buyTokenAddress=0xEURE12345678901234567890123456789012345678&amount=100.0&chainId=421614&provider=BOTH
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "quoteId": "abc123-def456-ghi789",
  "sellToken": "0xcb444e90d8198415266c6a2724b7900fb12fc56e",
  "sellTokenDecimals": 18,
  "buyToken": "0xEURE12345678901234567890123456789012345678",
  "buyTokenDecimals": 18,
  "sellAmount": "100.0",
  "feeAmount": "0.5",
  "buyAmount": "9950.25",
  "validTo": 1735689600,
  "comparisons": {
    "cowswap": {
      "provider": "COWSWAP",
      "buyAmount": "9950.25",
      "feeAmount": "0.5",
      "validTo": 1735689600
    },
    "oneinch": {
      "provider": "1INCH",
      "buyAmount": "9948.50",
      "estimatedGas": "150000"
    }
  },
  "bestProvider": "COWSWAP"
}

Balance Verification

Before executing the swap, verify that the user has sufficient tokens to sell. The API automatically checks the balance when requesting a quote, but you can also verify manually via:

Endpoint : GET /v1.2/bcreader/balances?address={safeAddress}

2. Execute Swap via SWAP_FROM_QUOTE

Once the quote is obtained, you can execute the swap using the SWAP_FROM_QUOTE operation.

Endpoint : POST /v1.2/safes/operations

Headers :

• Authorization: Bearer <access_token> (required)

Body (JSON) :

• safeAddress (string, required) : Safe address performing the swap
• operations (array, required) : Array containing an operation of type SWAP_FROM_QUOTE

SWAP_FROM_QUOTE Operation :

• type (string, required) : "SWAP_FROM_QUOTE"
• quoteId (string, required) : Quote identifier obtained in step 1

Request Example :

POST /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "operations": [
    {
      "type": "SWAP_FROM_QUOTE",
      "quoteId": "abc123-def456-ghi789"
    }
  ]
}

Response (200 OK) :

{
  "credentialRequestOptions": {
    "challenge": "<base64url_encoded_userOpHash>",
    "rpId": "foo.domain",
    "userVerification": "required"
  }
}

Finalize Execution (PUT)

Endpoint : PUT /v1.2/safes/operations

Body (JSON) :

• credential (object, required) : WebAuthn credential obtained with the options from the previous step

Request Example :

PUT /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "credential": {
    "id": "AVZs0qRCBSmfThZWu37g...",
    "rawId": "AVZs0qRCBSmfThZWu37g...",
    "type": "public-key",
    "response": {
      "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4/krrmihjLHmVzzuoMdl2MFAAAAAQ...",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoi...",
      "signature": "MEUCIQC..."
    }
  }
}

Response (200 OK) :

{
  "userOpHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "status": "SIGNED"
}

3. Track Operation Status

Once the operation is submitted, you can track its status. Possible statuses are:

• CREATED : Operation created, awaiting signature
• SIGNED : Operation signed, ready to be executed
• EXECUTED : Operation executed on the blockchain, awaiting confirmation
• CONFIRMED : Operation confirmed with sufficient blocks
• FAILED : Operation failed

Check Operation Status

Endpoint : GET /v1.2/safes/operations/{userOpHash}

Request Example :

GET /v1.2/safes/operations/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "userOpHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "status": "CONFIRMED",
  "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z"
}

Track Swap Order (v1.1 - Optional)

For CoW Protocol swaps, you can also track the swap order status via BCReader after execution:

Endpoint : POST /v1.1/swap/order/create (BCReader API)

Note : This endpoint is automatically called by the IBEX API after a CoW Protocol swap is signed. You can also call it manually to track swap orders.

Request Body :

• safeAddress (string, required) : Safe address that executed the swap
• uid (string, required for COWSWAP) : CoW Protocol order UID
• txHash (string, required for 1INCH) : 1INCH transaction hash
• provider (string, required) : "COWSWAP" or "1INCH"
• blockchainId (string, required) : Chain ID (e.g., "100" for Gnosis)

Request Example :

POST /v1.1/swap/order/create
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "uid": "0xd9c6...69069a35",
  "provider": "COWSWAP",
  "blockchainId": "100"
}

Response (200 OK) :

{
  "message": "Order surveillé créé",
  "order": {
    "id": 1,
    "uid": "0xd9c6...69069a35",
    "blockchainId": "100",
    "safeAddress": "0xfaa672c06e4abdcb4a1513e9a31c3c498a321468",
    "provider": "COWSWAP",
    "status": "fulfilled",
    "type": "traded",
    "executedSell": "8999454",
    "executedBuy": "7704892248123160929",
    "surplus": "0",
    "lastCheckedAt": "2025-11-02T12:10:35.000Z",
    "createdAt": "2025-11-02T12:10:34.000Z",
    "updatedAt": "2025-11-02T12:10:35.000Z"
  }
}

Get Swap Order Status : GET /v1.1/swap/order/{id}

You can retrieve a tracked swap order by UID or transaction hash:

Request Example (by UID) :

GET /v1.1/swap/order/0xd9c6...69069a35
Authorization: Bearer <access_token>

Request Example (by txHash) :

GET /v1.1/swap/order/0xswapTxHashReturnedAfterExecution
Authorization: Bearer <access_token>

4. Available Providers

The IBEX API supports two swap providers:

COWSWAP

• Decentralized swap provider using signed orders
• Best for large swaps
• Generally lower fees

1INCH

• DEX aggregator
• Best for small swaps
• Fast execution

5. Error Handling

Expired Quote

If the quote has expired, you will receive an error during execution. In this case, request a new quote.

Insufficient Balance

If the user does not have sufficient tokens to sell, the API will return an error. Check the balance before executing the swap.

Invalid Quote

If the quoteId is invalid or no longer exists, the API will return an error. Make sure to use a recent and valid quote.

Complete Flow Summary

1. Get a quote : GET /v1.2/safes/swap/quote with swap parameters
2. Store the quoteId : Store the quoteId received in the response
3. Prepare the swap : POST /v1.2/safes/operations with SWAP_FROM_QUOTE operation and the quoteId
4. Sign with passkey : Use navigator.credentials.get() with the credentialRequestOptions
5. Finalize execution : PUT /v1.2/safes/operations with the credential
6. Track status : Check status via GET /v1.2/safes/operations/{userOpHash}
7. Verify result : Once status = "CONFIRMED", the swap is complete

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX token swap flow, including architecture patterns, data models, and implementation details.

Quote Request Flow - Technical Details

GET /v1.2/safes/swap/quote

• Validates query parameters: sellTokenAddress, buyTokenAddress, amount, provider (optional)
• Resolves token information (address, decimals, symbol) from token registry
• Converts human-readable amount to wei using token decimals
• Fetches quotes from multiple providers in parallel:
  • CoW Protocol : Via requestQuote() from CoW client
  • 1inch : Via requestQuote() from 1inch client (if enabled)
• Persists quotes to database in UserQuote table (if userId available)
• Compares quotes and selects best provider based on buyAmount
• Returns unified response with quoteId, amounts, fees, and provider comparison

Database Schema - UserQuote:

UserQuote {
  id: String (PK, UUID)
  userId: String (FK to User)
  provider: String (COWSWAP | 1INCH)
  sellToken: String (address)
  buyToken: String (address)
  receiver: String (Safe address)
  sellAmount: String (wei, BigInt as string)
  buyAmount: String (wei, BigInt as string)
  validTo: Int (Unix timestamp)
  appData: String (JSON string)
  appDataHash: String
  kind: String (sell | buy)
  partiallyFillable: Boolean
  sellTokenBalance: String (erc20 | eth)
  buyTokenBalance: String (erc20 | eth)
  signingScheme: String (presign | eip712)
  createdAt: DateTime
  updatedAt: DateTime
}

SWAP_FROM_QUOTE Operation - Technical Details

POST /v1.2/safes/operations

• Operation type: SWAP_FROM_QUOTE
• Required parameter: quoteId (UUID of stored UserQuote)
• Loads quote from database using quoteId
• Determines provider from UserQuote.provider or appData.provider
• Creates Safe user operation based on provider:
  • 1INCH : Direct router call (approve + swap)
  • COWSWAP : MultiSend batch (approve + setPreSignature)
• Returns credentialRequestOptions with challenge = userOpHash
• Creates SafeOperation record with status CREATED
• Creates Operation record with type: SWAP_FROM_QUOTE and data: { quoteId, orderUid? }

1INCH Execution Flow:

• Gets spender address from 1inch API (getSpender())
• Creates two transactions in MultiSend batch:
  1. approve(sellToken, spender, sellAmount) : Approve token spending
  2. swap(router, swapData) : Execute swap via 1inch router
• Uses COW_MULTISEND_CALL_ADDRESS for MultiSend delegate call

CoW Protocol Execution Flow:

• Computes orderUid from quote data (deterministic hash)
• Uses idempotency cache to prevent duplicate orderUid generation
• Gets settlement contract address and relayer address from CoW client
• Creates two transactions in MultiSend batch:
  1. approve(sellToken, relayer, sellAmount) : Approve token spending
  2. setPreSignature(orderUid, true) : Pre-sign order for CoW settlement
• Uses COW_MULTISEND_CALL_ADDRESS for MultiSend delegate call

PUT /v1.2/safes/operations/{userOpHash}

• Verifies WebAuthn credential (passkey signature)
• Updates SafeOperation status to SIGNED
• For CoW Protocol: Calls BCReader POST /v1.1/swap/order/create with orderUid and provider
• Bundler automatically picks up signed operation and submits to blockchain
• Operation status transitions: CREATED → SIGNED → EXECUTED → CONFIRMED

Provider Comparison - Technical Details

Quote Response Structure:

{
  "quoteId": "uuid",
  "sellToken": "0x...",
  "sellTokenDecimals": 18,
  "buyToken": "0x...",
  "buyTokenDecimals": 18,
  "sellAmount": "1000000000000000000",  // Human-readable amount
  "feeAmount": "5000000000000000",      // CoW fee (if applicable)
  "buyAmount": "2000000000000000000",   // Expected output
  "validTo": 1234567890,                // Unix timestamp
  "comparisons": {
    "cowswap": {
      "provider": "COWSWAP",
      "buyAmount": "2000000000000000000",
      "feeAmount": "5000000000000000",
      "validTo": 1234567890
    },
    "oneinch": {
      "provider": "1INCH",
      "buyAmount": "1950000000000000000",
      "estimatedGas": "150000"
    }
  },
  "bestProvider": "COWSWAP"            // Selected provider
}

Provider Selection Logic:

• If provider query parameter specified: Use that provider (fail if unavailable)
• If both providers available: Compare buyAmount, select highest
• If only one provider available: Use that provider
• Default: Prefer CoW Protocol if both available

Idempotency and Concurrency Control

Per-Safe Execution Locks:

• In-memory safeExecutionLocks Set prevents concurrent execution for same Safe
• Lock acquired before operation preparation, released after completion
• Prevents nonce conflicts when multiple swap operations submitted simultaneously

Quote Idempotency:

• In-memory swapIdemCache Map stores (quoteId → orderUid) mappings
• Prevents duplicate orderUid generation for same quoteId
• Cache key: ${safeAddress}-${quoteId}
• TTL: Per-process (cleared on restart)

Operation Status Tracking

Status Flow:

• CREATED : Operation created, awaiting passkey signature
• SIGNED : Passkey signature received, operation ready for bundler
• EXECUTED : Bundler submitted userOp to blockchain, awaiting confirmation
• CONFIRMED : Sufficient block confirmations received (typically 1-2 blocks)
• FAILED : Operation failed (insufficient funds, slippage exceeded, etc.)

Status Polling:

• Use GET /v1.2/safes/operations/{userOpHash} to check status
• Poll every 2-5 seconds until status is CONFIRMED or FAILED
• Response includes receipt (transaction receipt) when confirmed
• Response includes error (error details) when failed

Error Handling

• 400 Bad Request : Missing quoteId, invalid quoteId, quote expired, insufficient balance
• 401 Unauthorized : Invalid JWT, missing Authorization header
• 403 Forbidden : User locked, insufficient permissions
• 404 Not Found : Quote not found, Safe address not found
• 409 Conflict : Nonce conflict, concurrent operation, duplicate orderUid
• 500 Internal Server Error : Provider API error, bundler error, database error

Key Implementation Files

• src/routes/v1/safes.ts : GET /v1.2/safes/swap/quote endpoint
• src/routes/v1/safesOperations.ts : SWAP_FROM_QUOTE operation handler
• src/clients/CoW.ts : CoW Protocol API client
• src/clients/OneInch.ts : 1inch API client
• prisma/schema.prisma : UserQuote model definition

Complete Flow - Technical Sequence

1. Request quote : GET /v1.2/safes/swap/quote → returns quoteId, amounts, provider comparison
2. Store quoteId : Client stores quoteId (valid for ~5 minutes)
3. Prepare swap : POST /v1.2/safes/operations with { type: "SWAP_FROM_QUOTE", quoteId }
4. Load quote : Server loads UserQuote from database
5. Create operation : Server creates Safe user operation (approve + swap/setPreSignature)
6. Get credential options : Server returns credentialRequestOptions with userOpHash
7. Sign with passkey : Client uses WebAuthn to sign challenge
8. Finalize execution : PUT /v1.2/safes/operations/{userOpHash} with credential
9. Operation signed : Server updates status to SIGNED, notifies BCReader (CoW only)
10. Bundler execution : Bundler picks up signed operation, submits to blockchain
11. Status tracking : Poll GET /v1.2/safes/operations/{userOpHash} until CONFIRMED
12. Swap complete : Once CONFIRMED, tokens have been swapped on-chain

← Back to Main Guide