Quotes API

Request, execute, and monitor swap quotes across chains

Overview

The Quotes API enables you to request price quotes for chain-abstracted swaps, execute those quotes, and monitor their execution status. This is the core API for performing token swaps in the OneBalance system.

API Methods

getQuote

Request a quote for swapping tokens across chains.

quotesApi.getQuote(request: QuoteRequest): Promise<Quote>

Parameters

request · QuoteRequest · required

The quote request object containing source and destination details

Show QuoteRequest Structure

from · object · required

Source account and asset information

Show from properties

account · object · required

sessionAddress · string · required

Session wallet address (typically embedded wallet)

adminAddress · string · required

Admin wallet address (typically same as session address)

accountAddress · string · required

Smart contract account address (predicted address)

asset · object · required

assetId · string · required

Aggregated asset ID (e.g., “ob:usdc”, “ob:eth”)

amount · string · required

Amount to swap in smallest unit (wei for ETH, base units for tokens)

to · object · required

Destination asset information

Show to properties

asset · object · required

assetId · string · required

Aggregated asset ID for destination token

account · string

Optional recipient address in CAIP format (e.g., “eip155:1:0x…”) for transfers to other accounts

amount · string

Optional exact output amount for reverse quotes

Returns

Quote · object

A quote object containing all information needed to execute the swap

Show Quote Structure

id · string

Unique identifier for this quote

account · object

Account information used for this quote

originToken · TokenInfo

Information about the source token and amount

Show TokenInfo properties

aggregatedAssetId · string

The aggregated asset identifier

amount · string

Token amount in base units

assetType · string | string[]

Individual asset type(s) in CAIP-19 format

destinationToken · TokenInfo

Information about the destination token and expected amount

expirationTimestamp · string

Unix timestamp when this quote expires (in seconds)

tamperProofSignature · string

Server signature ensuring quote integrity

originChainsOperations · ChainOperation[]

Array of operations to execute on source chain(s)

destinationChainOperation · ChainOperation

Optional operation for destination chain

Example

Example Request

import { quotesApi } from '@/lib/api/quotes';
import type { QuoteRequest } from '@/lib/types/quote';

const quoteRequest: QuoteRequest = {
  from: {
    account: {
      sessionAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      adminAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      accountAddress: '0x1234567890abcdef1234567890abcdef12345678'
    },
    asset: {
      assetId: 'ob:usdc'
    },
    amount: '1000000' // 1 USDC (6 decimals)
  },
  to: {
    asset: {
      assetId: 'ob:eth'
    }
  }
};

const quote = await quotesApi.getQuote(quoteRequest);
console.log('Quote ID:', quote.id);
console.log('Expected output:', quote.destinationToken.amount);

---

executeQuote

Execute a signed quote to perform the swap.

quotesApi.executeQuote(quote: Quote): Promise<any>

Before calling this function, you must sign the quote’s chain operations using the user’s wallet. The quote parameter should include signed userOp signatures.

Parameters

quote · Quote · required

The quote object with signed user operations. This should be the same quote returned from getQuote(), but with signatures added to each chain operation.

Returns

response · any

Execution confirmation response from the server

Example

Example Execution

import { quotesApi } from '@/lib/api/quotes';
import { signQuote } from '@/lib/utils/privySigningUtils';

// First, get a quote
const quote = await quotesApi.getQuote(quoteRequest);

// Check if quote is still valid
const expirationTime = parseInt(quote.expirationTimestamp) * 1000;
if (Date.now() > expirationTime) {
  throw new Error('Quote has expired');
}

// Sign the quote with user's wallet
const signedQuote = await signQuote(quote, embeddedWallet);

// Execute the signed quote
await quotesApi.executeQuote(signedQuote);

console.log('Quote executed successfully!');

---

getQuoteStatus

Check the execution status of a quote.

quotesApi.getQuoteStatus(quoteId: string): Promise<QuoteStatus>

This endpoint should be polled periodically after executing a quote to monitor transaction progress across chains.

Parameters

quoteId · string · required

The unique identifier of the quote to check (from quote.id)

Returns

QuoteStatus · object

Current status and transaction details

Show QuoteStatus Structure

quoteId · string

The quote identifier

status · 'PENDING' | 'COMPLETED' | 'FAILED' | 'IN_PROGRESS' | 'REFUNDED'

Current execution status

• PENDING: Quote executed, waiting for blockchain confirmation
• IN_PROGRESS: Transactions being processed
• COMPLETED: All transactions confirmed successfully
• FAILED: One or more transactions failed
• REFUNDED: Failed transaction with funds refunded

user · string

User account address

recipientAccountId · string

Recipient account identifier

originChainOperations · array

Transaction details from source chain(s)

Show Operation properties

hash · string

Transaction hash

chainId · number

Chain ID where transaction occurred

explorerUrl · string

Block explorer URL for the transaction

destinationChainOperations · array

Transaction details from destination chain

Example

Polling Example

import { quotesApi } from '@/lib/api/quotes';

// Start polling after executing a quote
const pollStatus = async (quoteId: string) => {
  const interval = setInterval(async () => {
    try {
      const status = await quotesApi.getQuoteStatus(quoteId);
      
      console.log('Status:', status.status);
      console.log('Origin txs:', status.originChainOperations);
      
      if (status.status === 'COMPLETED') {
        clearInterval(interval);
        console.log('Swap completed!');
        console.log('Explorer:', status.destinationChainOperations[0]?.explorerUrl);
      } else if (status.status === 'FAILED') {
        clearInterval(interval);
        console.error('Swap failed');
      }
    } catch (error) {
      console.error('Error checking status:', error);
      clearInterval(interval);
    }
  }, 1000); // Poll every 1 second
};

pollStatus(quote.id);

Complete Workflow Example

Here’s a complete example showing how to request, execute, and monitor a swap:

Complete Swap Flow

import { quotesApi } from '@/lib/api/quotes';
import { signQuote } from '@/lib/utils/privySigningUtils';
import type { QuoteRequest } from '@/lib/types/quote';

// Step 1: Create a quote request
const quoteRequest: QuoteRequest = {
  from: {
    account: {
      sessionAddress: walletAddress,
      adminAddress: walletAddress,
      accountAddress: smartAccountAddress
    },
    asset: { assetId: 'ob:usdc' },
    amount: '100000000' // 100 USDC
  },
  to: {
    asset: { assetId: 'ob:eth' }
  }
};

// Step 2: Get the quote
const quote = await quotesApi.getQuote(quoteRequest);
console.log('Quote received:', quote.id);
console.log('Will receive:', quote.destinationToken.amount, 'ETH');

// Step 3: Sign and execute
const signedQuote = await signQuote(quote, wallet);
await quotesApi.executeQuote(signedQuote);
console.log('Quote executed, monitoring status...');

// Step 4: Poll for status
const checkStatus = setInterval(async () => {
  const status = await quotesApi.getQuoteStatus(quote.id);
  
  if (status.status === 'COMPLETED' || status.status === 'FAILED') {
    clearInterval(checkStatus);
    console.log('Final status:', status.status);
  }
}, 2000);

Related Types

• QuoteRequest - Structure for requesting quotes
• Quote - Quote response structure
• QuoteStatus - Status response structure
• ChainOperation - Chain operation details

Error Handling

Error Handling Example

try {
  const quote = await quotesApi.getQuote(request);
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to get quote:', error.message);
    // Handle specific error cases
    if (error.message.includes('insufficient balance')) {
      // Show balance error to user
    } else if (error.message.includes('unsupported asset')) {
      // Show asset error to user
    }
  }
}

Best Practices

Check Expiration

Always validate that expirationTimestamp hasn’t passed before executing a quote

Poll Efficiently

Poll status every 1-2 seconds after execution, and stop when status is terminal (COMPLETED/FAILED)

Handle Errors

Implement proper error handling for network failures and transaction rejections

Show Progress

Display transaction hashes and explorer links to users for transparency