Trading API - Overview

📘
Beta Feature
The Trading API is currently in beta and subject to change. For participation details, contact your Fireblocks Customer Success Manager or email [email protected].

Introduction

The Fireblocks Trading API enables several use cases related to liquidity and conversions, executing trades directly from your Fireblocks workspace, integrating dApps and centralized providers. With it, you can create Orders for the following use cases:

Swap one asset to another on decentralized and centralized providers, over the same network. For example, swap USDC over Ethereum to USDT over Ethereum from one of your vaults via dApps like Uniswap or connected accounts like Scrypt
On/off ramp via connected accounts with one of the providers. For example, on-ramp MXN to USDC over Polygon via your connected account with Alfred Pay
Bridge assets between different chains via account-based providers (see On-Ramp, Off-Ramp, and Bridge/Swap via Account-Based Providers (CeFi))

Additional use cases:

Convert one asset to another within your connected account with account-based providers - to be added in the near future

This guide outlines the process for executing Orders using the Fireblocks API, including prerequisites, a detailed workflow, and necessary code examples for successful operations utilizing the different use cases mentioned above.

Core Terminology

Term	Description
Order	An instruction created through the trading API that defines what asset to buy or sell, at what price (market or quote), and how to settle it (DVP or prefunded). Each order has a unique ID and a lifecycle status that remains until it is completed or fails.
Quote	A temporary price offer from a provider that defines the exchange rate and expiry time. Quotes can be Indicative (for price preview only) or Committed (locked and executable until expiration).
Provider	External trading provider or exchange venue. For example, Bridge or AlfredPay for account-based providers, and Uniswap for direct access providers are commonly used in DeFi.
Settlement Type	Defines how and when funds move during a trade. - DVP: The provider waits for the user's fund deposit before executing the order, ensuring delivery occurs only after payment is received. - Prefunded: Executes instantly using the user's existing balance already held with the provider.
Execution Type	Defines how the order price is determined. - Market: Executes immediately at the best available rate from the provider. - Quote: Executes at a locked rate from a committed quote created beforehand using the Quote endpoint.
Participants Identification	Defines the originator and beneficiary involved in an order. Used to determine who initiates and who receives the transaction, and what level of PII data is required by the provider (e.g., first-party vs third-party).

Understanding Trading Providers

The Fireblocks Trading API supports two types of providers:

Direct Access Providers

DeFi platforms that provide direct access to decentralized protocols without requiring account management, such as Uniswap.

Key Characteristics:

Access Type: Direct - no account credentials needed
Approval: One-time Terms of Service acceptance

Account-Based Providers

Centralized providers that require users to open an account with them. Account-based access requires credentials (API keys).

Key Characteristics:

Access Type: Account-based - customers need to open an account with the provider before they can use the API to create Orders via Fireblocks. After creating the account, the customer needs to generate API keys within their account in the provider console, and then connect the account via the connected-account page in the Fireblocks console. For detailed instructions, see Fireblocks Connected Accounts

Prerequisites

1. Fireblocks API Credentials

Obtain API and Secret Keys from Fireblocks.
Ensure the credentials have sufficient permissions for trading operations.

2. SDK Installation

Install or update the Fireblocks SDK with trading support before proceeding.

3. Other Requirements

Different providers have specific requirements:

For direct access providers:

Trades execute on-chain, requiring gas fees in the native blockchain asset. For example, Ethereum-based swap orders via Uniswap will require you to have ETH for gas
The execution of direct access orders is done via smart contracts. Ensure you have policy rules that allow smart contract calls within your policy

For account-based orders:

Minimum trade amounts vary by platform
Execution and settlement are handled through connected accounts
Ensure you have both Orders and Transfer policy rules inside your policy

High-Level Trading Flow

1. List Providers
   │
   ├─→ GET /providers
   │   └─→ Returns available providers
   │
2. Approve Terms (For direct access only)
   │
   ├─→ One-time approval for direct access providers - Approved only from the console
   │
3. Create Quote (optional - some providers allow creating Market orders without creating a quote beforehand)
   │
   ├─→ POST /trading/quotes
   │   └─→ Get exchange rate, amounts, and fees
   │
4. Create Order
   │
   ├─→ POST /trading/orders
   │   ├─→ Using quote (quote-based execution)
   │   └─→ Direct market order
   │
5. Monitor Order
   │
   └─→ GET /trading/orders/{orderId}
       └─→ Track execution status and completion

Next Steps

See the following guides for implementation examples:

Swap via Direct Access Providers (DeFi) - Step-by-step guide for executing swaps using direct access providers like Uniswap
On-Ramp, Off-Ramp, and Bridge/Swap via Account-Based Providers (CeFi) - Step-by-step guide for on-ramp, off-ramp, and swap operations using account-based providers