Quote Types

Type definitions for quote requests, responses, and operations in OneBalance

Overview

The Quote types define the structure for requesting and receiving swap quotes, including account information, token details, and chain-specific operations.

QuoteRequest

Defines the structure for requesting a quote for a swap or transfer.

export interface QuoteRequest {
  from: {
    account: {
      sessionAddress: string;
      adminAddress: string;
      accountAddress: string;
    };
    asset: {
      assetId: string;
    };
    amount: string;
  };
  to: {
    asset: {
      assetId: string;
    };
    account?: string; // Optional CAIP account ID for transfers to other accounts
    amount?: string; // Optional for quotes (used for exact output)
  };
}

Properties

from · object · required

Source information for the swap

Show from properties

account · object · required

Account details for the sender

Show account properties

sessionAddress · string · required

The session address for the account

adminAddress · string · required

The admin address that controls the account

accountAddress · string · required

The main account address

asset · object · required

Asset to swap from

Show asset properties

assetId · string · required

The aggregated asset ID (e.g., ob:eth, ob:usdc)

amount · string · required

Amount to swap in string format (BigInt as string)

to · object · required

Destination information for the swap

Show to properties

asset · object · required

Asset to swap to

Show asset properties

assetId · string · required

The aggregated asset ID (e.g., ob:eth, ob:usdc)

account · string

Optional CAIP account ID for transfers to other accounts

amount · string

Optional amount for exact output quotes. If not specified, the quote will be for exact input.

Example

const quoteRequest: QuoteRequest = {
  from: {
    account: {
      sessionAddress: "0x1234...",
      adminAddress: "0x5678...",
      accountAddress: "0x9abc..."
    },
    asset: {
      assetId: "ob:usdc"
    },
    amount: "1000000000" // 1000 USDC (6 decimals)
  },
  to: {
    asset: {
      assetId: "ob:eth"
    }
  }
};

---

Quote

Represents a complete quote response with all chain operations needed to execute the swap.

export interface Quote {
  id: string;
  account: Account;
  originToken: TokenInfo;
  destinationToken: TokenInfo;
  expirationTimestamp: string;
  tamperProofSignature: string;
  originChainsOperations: ChainOperation[];
  destinationChainOperation?: ChainOperation;
}

Properties

id · string · required

Unique identifier for the quote

account · Account · required

Account information for the quote. See Account below.

originToken · TokenInfo · required

Information about the source token. See TokenInfo below.

destinationToken · TokenInfo · required

Information about the destination token. See TokenInfo below.

expirationTimestamp · string · required

ISO timestamp when the quote expires

tamperProofSignature · string · required

Cryptographic signature ensuring quote integrity

originChainsOperations · ChainOperation[] · required

Array of operations to execute on origin chains. See ChainOperation below.

destinationChainOperation · ChainOperation

Optional operation to execute on the destination chain. See ChainOperation below.

---

Account

Account information structure used in quotes.

export interface Account {
  sessionAddress: string;
  adminAddress: string;
  accountAddress: string;
}

Properties

sessionAddress · string · required

The session address for the account

adminAddress · string · required

The admin address that controls the account

accountAddress · string · required

The main account address

---

TokenInfo

Information about a token involved in a quote.

export interface TokenInfo {
  aggregatedAssetId: string;
  amount: string;
  assetType: string | string[];
  fiatValue: never;
}

Properties

aggregatedAssetId · string · required

The aggregated asset identifier (e.g., ob:eth, ob:usdc)

amount · string · required

Token amount in string format (BigInt as string)

assetType · string | string[] · required

CAIP-19 format asset type(s). Can be a single asset type or array of asset types when aggregated across multiple chains.

Example: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" (USDC on Ethereum)

fiatValue · never · required

Fiat value placeholder (not used in quote context)

---

ChainOperation

Defines a user operation to be executed on a specific chain.

export interface ChainOperation {
  userOp: {
    sender: string;
    nonce: string;
    callData: string;
    callGasLimit: string;
    verificationGasLimit: string;
    preVerificationGas: string;
    maxFeePerGas: string;
    maxPriorityFeePerGas: string;
    paymaster: string;
    paymasterVerificationGasLimit: string;
    paymasterPostOpGasLimit: string;
    paymasterData: string;
    signature: string;
  };
  typedDataToSign: {
    domain: unknown;
    types: unknown;
    primaryType: string;
    message: unknown;
  };
  assetType: string;
  amount: string;
}

Properties

userOp · object · required

ERC-4337 User Operation parameters

Show userOp properties

sender · string · required

The account making the operation

nonce · string · required

Anti-replay parameter

callData · string · required

The data to pass to the sender during the main execution call

callGasLimit · string · required

The amount of gas to allocate the main execution call

verificationGasLimit · string · required

The amount of gas to allocate for the verification step

preVerificationGas · string · required

The amount of gas to pay for to compensate the bundler for pre-verification execution

maxFeePerGas · string · required

Maximum fee per gas (similar to EIP-1559 max_fee_per_gas)

maxPriorityFeePerGas · string · required

Maximum priority fee per gas (similar to EIP-1559 max_priority_fee_per_gas)

paymaster · string · required

Address of paymaster contract, zero address if not using paymaster

paymasterVerificationGasLimit · string · required

The amount of gas to allocate for the paymaster validation code

paymasterPostOpGasLimit · string · required

The amount of gas to allocate for the paymaster post-operation code

paymasterData · string · required

Data for paymaster (only if paymaster is not zero address)

signature · string · required

Data passed into the account along with the nonce during the verification step

typedDataToSign · object · required

EIP-712 typed data structure for signing

Show typedDataToSign properties

domain · unknown · required

The domain separator for EIP-712

types · unknown · required

The type definitions for the structured data

primaryType · string · required

The primary type being signed

message · unknown · required

The message to sign

assetType · string · required

CAIP-19 format asset type identifier for this operation

amount · string · required

Amount being transferred in this operation (as string)

---

QuoteStatus

Tracking information for an executed quote.

export interface QuoteStatus {
  quoteId: string;
  status: 'PENDING' | 'COMPLETED' | 'FAILED' | 'IN_PROGRESS' | 'REFUNDED';
  user: string;
  recipientAccountId: string;
  originChainOperations: {
    hash: string;
    chainId: number;
    explorerUrl: string;
  }[];
  destinationChainOperations: {
    hash: string;
    chainId: number;
    explorerUrl: string;
  }[];
}

Properties

quoteId · string · required

The ID of the quote being tracked

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

Current status of the quote execution

• PENDING: Quote created but execution not started
• IN_PROGRESS: Execution has started
• COMPLETED: All operations completed successfully
• FAILED: Execution failed
• REFUNDED: Failed execution has been refunded

user · string · required

The user address who initiated the quote

recipientAccountId · string · required

The recipient account identifier

originChainOperations · array · required

Array of transaction details from origin chains

Show operation properties

hash · string · required

Transaction hash

chainId · number · required

Chain ID where the transaction was executed

explorerUrl · string · required

Block explorer URL for the transaction

destinationChainOperations · array · required

Array of transaction details from destination chain

Show operation properties

hash · string · required

Transaction hash

chainId · number · required

Chain ID where the transaction was executed

explorerUrl · string · required

Block explorer URL for the transaction

Example

const status: QuoteStatus = {
  quoteId: "quote_123abc",
  status: "COMPLETED",
  user: "0x1234...",
  recipientAccountId: "eip155:1:0x5678...",
  originChainOperations: [
    {
      hash: "0xabcd...",
      chainId: 1,
      explorerUrl: "https://etherscan.io/tx/0xabcd..."
    }
  ],
  destinationChainOperations: [
    {
      hash: "0xef01...",
      chainId: 137,
      explorerUrl: "https://polygonscan.com/tx/0xef01..."
    }
  ]
};