Get transaction history

Authorizations

x-api-key

string

header

required

The OneBalance API uses API keys to authenticate requests. All API requests require authentication using an API key passed in the x-api-key header:

curl -X 'GET' \
  'https://be.onebalance.io/api/path-to/endpoint' \
  -H 'x-api-key: ${ONEBALANCE_API_KEY}' \
  ...

A public API key is available for testing purposes with limited usage: 42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Learn how to generate API access tokens at OneBalance Docs.

Query Parameters

user

string

required

The address for which to retrieve the transaction history

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

limit

integer

default:20

Maximum number of transactions to return

Required range: x >= 1

Example:

10

continuation

string

The continuation string for retrieving the next page of transactions

Example:

"txn_00123456789abcdef"

sortBy

enum<string>

default:createdAt

Field to sort the transaction history by. Defaults to createdAt if not specified.

Available options:

createdAt,

updatedAt

Example:

"createdAt"

Response

Successfully retrieved the transaction history

transactions

object[]

required

List of transactions for the user

Show child attributes

transactions.quoteId

string

required

Quote ID of the execution

Example:

"0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"

transactions.status

enum<string>

required

Execution status of the quote

Available options:

PENDING,

IN_PROGRESS,

EXECUTED,

COMPLETED,

REFUNDED,

FAILED

Example:

{ "status": "COMPLETED" }

transactions.user

string

required

The address of the user that initiated the quote

Example:

"0x9b747cC14A5672a7166b4eccdc92d7F4003f8081"

transactions.recipientAccountId

string

required

Recipient account identifier (e.g., eip155:chainId/address).

Example:

"eip155:1/0x9b747cC14A5672a7166b4eccdc92d7F4003f8081"

transactions.originChainOperations

object[]

required

The asset(s) that were sent from the source

Show child attributes

transactions.originChainOperations.hash

string

required

The hash of the transaction

Example:

"0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"

transactions.originChainOperations.chainId

integer

required

The chain ID of the transaction

Example:

1

transactions.originChainOperations.chain

string

required

The CAIP-2 identifier for the chain

Example:

"eip155:1"

transactions.originChainOperations.explorerUrl

string<url>

required

Explorer URL of the transaction

Example:

"https://etherscan.io/tx/0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"

Example:

[
  {
    "hash": "0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d",
    "chainId": 1,
    "explorerUrl": "https://etherscan.io/tx/0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"
  }
]

transactions.destinationChainOperations

object[]

required

The asset(s) that were received to the final destination

Show child attributes

transactions.destinationChainOperations.hash

string

required

The hash of the transaction

Example:

"0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"

transactions.destinationChainOperations.chainId

integer

required

The chain ID of the transaction

Example:

1

transactions.destinationChainOperations.chain

string

required

The CAIP-2 identifier for the chain

Example:

"eip155:1"

transactions.destinationChainOperations.explorerUrl

string<url>

required

Explorer URL of the transaction

Example:

"https://etherscan.io/tx/0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"

Example:

[
  {
    "hash": "0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d",
    "chainId": 1,
    "explorerUrl": "https://etherscan.io/tx/0xfa6094cd9d65416c975e3498cc5c2ca17df6c4cfa37e16f84f2736296dd98b5d"
  }
]

transactions.type

enum<string>

required

The type of transaction initiated by the user

Available options:

SWAP,

TRANSFER,

BRIDGE,

CALL

Example:

"SWAP"

transactions.originToken

object

required

The token(s) that were sent from the source

Show child attributes

transactions.originToken.aggregatedAssetId

string

required

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

Example:

"ob:eth"

transactions.originToken.amount

string

required

The amount of the token

Example:

"1000000000000000000"

transactions.originToken.assetType

string[]

required

The type of the individual assets (e.g., eip155:1/erc20:... or eip155:1/slip44:...)

Example:

[
  "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
  "eip155:1/slip44:60"
]

transactions.originToken.fiatValue

object[]

required

The fiat values of the individual asset types

Show child attributes

transactions.originToken.fiatValue.assetType

string

required

The CAIP-19 asset type identifier (e.g., eip155:1/erc20:... or eip155:1/slip44:...).

Example:

"eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"

transactions.originToken.fiatValue.fiatValue

string

required

The fiat value of the individual asset in USD

Example:

"100"

Example:

[
  {
    "assetType": "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
    "fiatValue": "1800.00"
  },
  {
    "assetType": "eip155:1/slip44:60",
    "fiatValue": "1800.00"
  }
]

transactions.destinationToken

object

required

The token(s) that were received to the final destination

Show child attributes

transactions.destinationToken.aggregatedAssetId

string

required

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

Example:

"ob:usdc"

transactions.destinationToken.amount

string

required

The amount of the token

Example:

"100000000"

transactions.destinationToken.assetType

string

required

The type of the individual asset (e.g., eip155:1/erc20:... or eip155:1/slip44:...)

Example:

"eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"

transactions.destinationToken.fiatValue

string

required

The fiat value of the individual asset in USD

Example:

"100"

transactions.destinationToken.minimumAmount

string

The minimum amount of the token

Example:

"100"

transactions.destinationToken.minimumFiatValue

string

The minimum fiat value of the token

Example:

"100"

transactions.destinationToken.symbol

string

The token symbol (e.g., USDC, ETH)

Example:

"USDC"

transactions.destinationToken.name

string

The human-readable name of the token

Example:

"USDC"

transactions.destinationToken.decimals

integer

The number of decimal places for the token

Example:

18

transactions.destinationToken.recipientAccount

string

The recipient account address with chain identifier where the destination tokens will be received

Example:

"eip155:42161:0x895Cf62399bF1F8b88195E741b64278b41EB7F09"

transactions.timestamp

string<date-time>

required

The timestamp of the transaction

Example:

"2024-01-01T00:00:00.000Z"

transactions.failReason

enum<string>

Reason for quote refund when status is REFUNDED.

For detailed explanations and troubleshooting steps, see: https://docs.onebalance.io/api-reference/error-codes

Possible values:

General Failure Reasons:

UNKNOWN: Unknown failure reason
SLIPPAGE: Price moved beyond the configured slippage tolerance
AMOUNT_TOO_LOW_TO_REFUND: Amount is too low to process a refund
DEPOSIT_ADDRESS_MISMATCH: Deposit address does not match expected address
DEPOSIT_CHAIN_MISMATCH: Deposit chain does not match expected chain
INCORRECT_DEPOSIT_CURRENCY: Deposited currency is incorrect
DOUBLE_SPEND: Double spend detected
SOLVER_CAPACITY_EXCEEDED: Solver capacity has been exceeded
DEPOSITED_AMOUNT_TOO_LOW_TO_FILL: Deposited amount is too low to fill the order
NEGATIVE_NEW_AMOUNT_AFTER_FEES: Negative amount after deducting fees
NO_QUOTES: No quotes available
MISSING_REVERT_DATA: Missing revert data from transaction
REVERSE_SWAP_FAILED: Reverse swap operation failed
GENERATE_SWAP_FAILED: Failed to generate swap
TOO_LITTLE_RECEIVED: Received amount is too little
EXECUTION_REVERTED: Execution was reverted
NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE: New calldata includes higher rent fee
TRANSACTION_REVERTED: Transaction was reverted
ORIGIN_CURRENCY_MISMATCH: Origin currency mismatch
NO_INTERNAL_SWAP_ROUTES_FOUND: No internal swap routes found
SWAP_USES_TOO_MUCH_GAS: Swap uses too much gas
INSUFFICIENT_FUNDS_FOR_RENT: Insufficient funds for rent (Solana-specific)

Execution Revert Specific Reasons:

ORDER_EXPIRED: Order has expired
ORDER_IS_CANCELLED: Order has been cancelled
TRANSFER_FROM_FAILED: Transfer from operation failed
TRANSFER_FAILED: Transfer operation failed
SIGNATURE_EXPIRED: Signature has expired
INVALID_SIGNATURE: Invalid signature provided
INSUFFICIENT_NATIVE_TOKENS_SUPPLIED: Insufficient native tokens supplied
TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE: Transfer amount exceeds allowance
TRANSFER_AMOUNT_EXCEEDS_BALANCE: Transfer amount exceeds balance
INVALID_SENDER: Invalid sender
ACCOUNT_ABSTRACTION_INVALID_NONCE: Account abstraction invalid nonce
ACCOUNT_ABSTRACTION_SIGNATURE_ERROR: Account abstraction signature error
SEAPORT_INEXACT_FRACTION: Seaport inexact fraction
TOKEN_NOT_TRANSFERABLE: Token is not transferable
ZERO_SELL_AMOUNT: Zero sell amount
MINT_NOT_ACTIVE: Mint is not active
ERC_1155_TOO_MANY_REQUESTED: ERC-1155 too many requested
INCORRECT_PAYMENT: Incorrect payment
INVALID_GAS_PRICE: Invalid gas price
FLUID_DEX_ERROR: Fluid DEX error
ORDER_ALREADY_FILLED: Order already filled
SEAPORT_INVALID_FULFILLER: Seaport invalid fulfiller

Jupiter Specific Failures:

JUPITER_INVALID_TOKEN_ACCOUNT: Jupiter invalid token account (Solana)

Available options:

UNKNOWN,

SLIPPAGE,

AMOUNT_TOO_LOW_TO_REFUND,

DEPOSIT_ADDRESS_MISMATCH,

DEPOSIT_CHAIN_MISMATCH,

INCORRECT_DEPOSIT_CURRENCY,

DOUBLE_SPEND,

SOLVER_CAPACITY_EXCEEDED,

DEPOSITED_AMOUNT_TOO_LOW_TO_FILL,

NEGATIVE_NEW_AMOUNT_AFTER_FEES,

NO_QUOTES,

MISSING_REVERT_DATA,

REVERSE_SWAP_FAILED,

GENERATE_SWAP_FAILED,

TOO_LITTLE_RECEIVED,

EXECUTION_REVERTED,

NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE,

TRANSACTION_REVERTED,

ORIGIN_CURRENCY_MISMATCH,

NO_INTERNAL_SWAP_ROUTES_FOUND,

SWAP_USES_TOO_MUCH_GAS,

INSUFFICIENT_FUNDS_FOR_RENT,

ORDER_EXPIRED,

ORDER_IS_CANCELLED,

TRANSFER_FROM_FAILED,

TRANSFER_FAILED,

SIGNATURE_EXPIRED,

INVALID_SIGNATURE,

INSUFFICIENT_NATIVE_TOKENS_SUPPLIED,

TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE,

TRANSFER_AMOUNT_EXCEEDS_BALANCE,

INVALID_SENDER,

ACCOUNT_ABSTRACTION_INVALID_NONCE,

ACCOUNT_ABSTRACTION_SIGNATURE_ERROR,

SEAPORT_INEXACT_FRACTION,

TOKEN_NOT_TRANSFERABLE,

ZERO_SELL_AMOUNT,

MINT_NOT_ACTIVE,

ERC_1155_TOO_MANY_REQUESTED,

INCORRECT_PAYMENT,

INVALID_GAS_PRICE,

FLUID_DEX_ERROR,

ORDER_ALREADY_FILLED,

SEAPORT_INVALID_FULFILLER,

JUPITER_INVALID_TOKEN_ACCOUNT

Example:

"SLIPPAGE"

continuation

string

String to provide in order to fetch the next page of results

Example:

"txn_00123456789abcdef"

API Reference

EVM Operations

Multi-Chain Operations

Platform Data

Authorizations

Query Parameters

Response