What's broker api?

The Broker API: Asynchronous Swap Flow

The Hibit Broker API offers a flexible and powerful asynchronous flow for integrating omnichain trading. This model is ideal for scenarios requiring a multi-step, stateful process, such as complex integrations where a single, all-in-one wallet signature isn't practical.

The core principle remains entirely non-custodial: the user initiates a transfer, and Hibit's backend orchestrates the entire swap, delivering the final asset directly to the user's specified return address, even if it's on a different blockchain.

How It Works: The Asynchronous Swap Flow

To successfully execute a trade using this model, your application must follow these sequential steps. Each step corresponds to a specific API call that orchestrates the swap from start to finish.

Step 1: Generate a Payment Address Before a user can initiate the swap, your application must request a unique, single-use address from Hibit.

• API Endpoint: GET /api/v1/broker/get-payment-address

• Purpose: To generate a secure address where the user will send the asset they wish to swap (fromToken). This address acts as a secure routing point for this specific transaction.

Step 2: User Sends Assets & You Capture the Transaction Hash This is a user-driven action. The user sends their funds to the address provided in Step 1.

• Action: The user initiates a standard blockchain transaction from their wallet.

• Your Responsibility: Your application must monitor for this transaction and retrieve its unique transaction hash (txid). This txid serves as the crucial link between the user's on-chain action and the intended swap.

Step 3: Get a Swap Quote With the user's transfer initiated, you can now fetch a real-time quote for the desired swap.

• API Endpoint: GET /api/v1/broker/quote

• Purpose: To get the current exchange rate, fees, and the final amount of the toToken the user will receive.

Step 4: Execute the Swap This is the final execution step. You link the user's on-chain transfer with the swap details to trigger the backend process.

• API Endpoint: POST /api/v1/broker/swap

• Purpose: You provide the txid from the user's transfer, along with the quote details and, critically, the toAddress and toChain for the return assets. This tells the Hibit system to watch for the confirmation of the incoming transaction, verify it, and then execute the swap, sending the final assets to the user's destination wallet. The API will respond with a bizId, a unique identifier for this trade.

Step 5: Track the Order Status After execution, you can monitor the trade's progress until completion.

• API Endpoint: GET /api/v1/broker/get-agent-order

• Purpose: Use the bizId from Step 4 to poll this endpoint. It provides the real-time status of the order. A Success status means the trade is complete, and the response will include the toTx—the transaction hash of the final assets being sent to the user's designated return address.

Visual Workflow

Generated code

+----------------+      +---------------------------+      +-------------------+
|    Your App    |----->| GET /get-payment-address  |----->|  Hibit API        |
+----------------+      +---------------------------+      +-------------------+
       |                                                    (Returns Payment Addr)
       |
       v
+----------------+      +---------------------------+      +-------------------+
|   User Action  |----->|   Sends funds to Addr     |----->|  Blockchain       |
+----------------+      +---------------------------+      +-------------------+
       |                                                    (Generates txid)
       | (Your app gets the txid)
       v
+----------------+      +---------------------------+      +-------------------+
|    Your App    |----->|      GET /quote           |----->|  Hibit API        |
+----------------+      +---------------------------+      +-------------------+
       |                                                    (Returns Quote)
       v
+----------------+      +---------------------------+      +-------------------+
|    Your App    |----->| POST /swap (with txid     |----->|  Hibit API        |
|                |      | & user's return address)  |      |                   |
+----------------+      +---------------------------+      +-------------------+
       |                                                    (Returns bizId)
       v
+----------------+      +---------------------------+      +-------------------+
|    Your App    |----->| GET /get-agent-order      |----->|  Hibit API        |
| (polls status) |      | (with bizId)              |      | (Returns Status   |
+----------------+      +---------------------------+      |  & Final tx)      |
                                                            +-------------------+
                                                                   |
                                                                   v
                                                            +-------------------+
                                                            |  Final Assets     |
                                                            |  Sent to User's   |
                                                            |  Return Address   |
                                                            +-------------------+