Guides

BluefinX Integration Guide

Suggest Edits

Introduction

We're enhancing our Spot offering with BluefinX - a permissionless Request for Quote (RFQ) system with an off-chain auction for bids and on-chain execution. We expect that BluefinX quotes, inherently benefiting from speed, no MEV and no slippage will almost always win; driving fee capture on major pairs across the ecosystem to the participating Execution Agents and Bluefin.

System Overview and Design

BluefinX system enables Execution Agents to bid on quotes, with the best bid selected by the BluefinX API and forwarded to the frontend users to accept and sign. Execution Agents must deposit funds to a dedicated vault smart contract (shared object) to facilitate transactions, ensure bid signatures are valid, and maintain compliance with operational guidelines to avoid penalties. User swaps will be executed against this vault, and Bluefin’s order routing system will consider both quotes and Aggregator routes to determine maximum price efficiency for the user.


Key Benefits

✅ Best Pricing – Aggregates quotes from multiple Execution Agents to ensure the most competitive price

✅ Fast Execution – Instant price discovery and execution with minimal latency

✅ On-Chain Settlement – Secure transactions with cryptographic signatures for trustless execution.

✅ No Slippage – Trades are filled at their quoted price with no slippage

✅ MEV Protection – Quotes are exclusive to the taker requesting them

BluefinX Operational Flow

  1. Execution Agents create a vault
  • The vault is used to hold the tokens for swaps
  1. Execution Agents deposit tokens to the vault
  • The Agents will first need to mark the coin as supported in the targeted vault and decide the minimum amount that can be deposited to the vault
  • Once the coin is supported, Execution Agents can then deposit the funds corresponding to that coin.
  • It will be the Agent’s responsibility to Monitor and rebalance the vault funds as necessary to cover active bids.
  1. Users request a quote
  • The user specifies:
    • tokenInType (token to swap from)
    • tokenOutType (token to receive)
    • tokenInAmount (amount to swap)
  1. Bluefin’s backend sends the request to the Execution Agents
  • The request is sent to the Bluefin backend.
  • Bluefin checks which Execution Agents support both tokens.
  • The request is broadcasted in parallel to all participating Agents.
  1. Execution Agents respond with a quote
  • The Agents have 500ms to respond with a quote.
  • Each quote includes:
    • Token out amount
    • Vault Address
    • Creation Time (createdAtUtcMillis)
    • Expiration Time (quoteExpiresAtUtcMillis)
    • Signature (signed by vault manager, to be used for on-chain verification and successful execution of swap)
  1. Best quote selection
  • After 500ms, Bluefin determines the best quote.
  • The best quote is sent back to the frontend with all required details.
  1. User decides to swap
  • The user has until quoteExpiresAtUtcMillis to sign and execute the swap.
  • If the user decides to proceed:
    • The frontend will query the BluefinX service to sponsor the user’s transaction. This is because Bluefin is responsible for sponsoring gas of the BluefinX protocol.
    • Once the FE receives the sponsored transaction, it will ask the user to sign the transaction.
    • FE will send back the Tx bytes along with the user signature and quote id to the BluefinX service (This is a partially signed transaction)
    • BluefinX will check which Execution Agents provided the quote and will ask them if the quote is still valid and can be executed.
    • Once approved by the Execution Agents, Bluefin will finish signing the transaction that was partially signed, becoming the sponsor and submitting the transaction to the chain for execution
    • The swap is executed on-chain using:
      • User’s partially signed transaction
      • Bluefin's Sponsorship Signed Transaction (Fully signed)
      • Execution Agent’s quote signature
      • Vault address for settlement

Creating and managing a vault

Both Python and Typescript SDKs have support for creating and managing a Vault on the BluefinX protocol. Here is a quick example of how to create and manage a Vault using the Python SDK:

from bluefin_rfq_client import *

#-----------------INITIALIZING THE CLIENT-----------------

# Seed phrase (mnemonic) of the wallet
TEST_ACCT_PHRASE = "wallet seed phrase"

# RPC URL of the chain
TEST_NETWORK = "https://fullnode.mainnet.sui.io:443"

# Initialize SuiWallet using seed
wallet = SuiWallet(seed=TEST_ACCT_PHRASE)

# Read the contracts config (you can also specify filepath as an argument to read_json, by default it looks for rfq-contracts.json at root of working directory )
contracts_config = read_json()

# Initialize RFQContracts instance using the contract conffigs
rfq_contracts = RFQContracts(contracts_config)

# Initialize RFQClient
rfq_client = RFQClient(wallet=wallet, url=TEST_NETWORK, rfq_contracts=rfq_contracts)

#-----------------TO CREATE A VAULT-----------------

#To create a vault, use
success, response = rfq_client.create_vault(
    manager="0x67399451f127894ee0f9ff7182cbe914008a0197a97b54e86226d1c33635c368"
)

#-----------------TO DEPOSIT COINS IN A VAULT-----------------

#To deposit in a vault, use
success, response = rfq_client.deposit_in_vault(
   vault = "0x086156df8640740e10d835df9662a042e4e01d0f6471879e8fe8838954da934b",
   amount= "26900000",
   token_type = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
)

#-----------------TO WITHDRAW COINS FROM A VAULT-----------------

#To withdraw coins from a vault, use
success, response = rfq_client.withdraw_from_vault(
   vault = "0x086156df8640740e10d835df9662a042e4e01d0f6471879e8fe8838954da934b",
   amount= "26900000",
   token_type = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
)

#-----------------TO ADD SUPPORT FOR A COIN IN A VAULT-----------------

#To add support for a coin in a vault, use
success, response = rfq_client.add_supported_coin(
   vault = "0x086156df8640740e10d835df9662a042e4e01d0f6471879e8fe8838954da934b",
   min_deposit_amount= "1000000",
   token_type = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
)

#-----------------TO GET CURRENT COIN BALANCE IN A VAULT-----------------

#To get the current coin balance in a vault, use
balance = rfq_client.get_vault_coin_balance(
	 vault  = "0x086156df8640740e10d835df9662a042e4e01d0f6471879e8fe8838954da934b"
	 token_type = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
)

For a more detailed and complete guide on using the RFQClient in python please refer to our docs here.

BluefinX API

The BluefinX API allows Bluefin to source liquidity by requesting competitive quotes from multiple Execution Agents. This API enables low-latency and efficient token swaps by providing access to real-time pricing and execution.

Request for Quote (POST /api/rfq)

This endpoint must be implemented by Execution Agents. It will be called by Bluefin whenever a user requests a quote. Execution Agents respond with a quote, including the exchange rate, execution details, and expiry time.

The timeout of the endpoint is 500ms, if it’s slower, the connection is closed by the server.

Both token in and token out types must be supported, and the Execution Agents should share the list of supported tokens beforehand.

The open-api specs for the implementation of this endpoint are available here.

Once you support this endpoint please reach out to the Bluefin team (open a ticket in our Discord channel) with your host domain for quote forwarding.

Example response

{
    "quoteId": "7c7b4b89-8dc9-4220-8dc0-ab1abd88ee60",
    "taker": "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c",
    "tokenInType": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
    "tokenOutType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
    "tokenInAmount": "100000",
    "tokenOutAmount": "100000000",
    "signature": "MEUCIQDPsB7bCrOz7...",
    "vault": "0x443cf42b0da43c230bff7a64e69ce25d24d65f49e7c9db6adecc0bd176dba79a",
    "marketMakerAddress": "0x60dd01bc037e2c1ea2aaf02187701f9f4453ba323338d2f2f521957065b0984d",
    "createdAtUtcMillis": 1738650202708,
    "quoteExpiresAtUtcMillis": 1738650219043
}

Confirmation for swap execution for quotes (POST /api/rfq/swap)

This endpoint must also be implemented by Execution Agents, and it is used to verify the quote before the swap is executed. A detailed description of this feature’s flow is outlined here.

The open-api specs for the implementation of this endpoint are available here

Example response

{
    "approved": true,
    "executed": true
    "txDigest": "AXuPjE4rVYKqmNe8tPKakJ6Fx9zZX4vZNeT2viZpGh8Q" // Optional
}

Trades Feed (GET /api/rfq/swaps)

The endpoint is offered by Bluefin, allowing to retrieve swap records filtered by one or more vault IDs and quote IDs. It supports cursor-based pagination and the records are paginated based on the block_timestamp.

Query Parameters:

  • vault_ids: An array of vault IDs.
  • quote_ids: An array of quote IDs.
  • cursor: A block_timestamp value. Only records with a block_timestamp greater than this value will be returned.
  • limit: The maximum number of records to return.

The open-api specs are available here.

Example response

{
  "data": [
    {
      "vault_id": "vault1",
      "quote_id": "quote1",
      "taker": "0xABCDEF123456",
      "token_in_type": "BLUE",
      "token_out_type": "SUI",
      "token_in_amount": 100000000000,
      "token_out_amount": 20000000000,
      "fee": 1000000,
      "tx_hash": "0xabcdef1234567890",
      "tx_index": "0",
      "log_index": "1",
      "block_timestamp": 1672500000
    },
    {
      "vault_id": "vault2",
      "quote_id": "quote2",
      "taker": "0x123456ABCDEF",
      "token_in_type": "BTC",
      "token_out_type": "USDT",
      "token_in_amount": 500000,
      "token_out_amount": 30000000000,
      "fee": 5000000,
      "tx_hash": "0x1234567890ABCDEF",
      "tx_index": "1",
      "log_index": "2",
      "block_timestamp": 1672490000
    }
  ],
  "next_cursor": 1672490000
}

Authentication & Security

API Key Usage

The endpoint allows to define an optional x-api-key header. The API key should be shared by private channels and will be encrypted on the server side. When the request is sent, it is included in the request header and it is the Execution Agent’s responsibility to check the validity of the API key.

Generating Quote Signature

Both Python and Typescript SDKs have support to sign quotes and interact with the bluefin RFQ protocol on SUI. Here is a quick example of how to create and sign a Quote using the Python SDK:

from bluefin_rfq_client import *

# Seed phrase (mnemonic) of the wallet
TEST_ACCT_PHRASE = "wallet seed phrase"

# RPC URL of the chain
TEST_NETWORK = "https://fullnode.mainnet.sui.io:443"

# Initialize SuiWallet using seed
wallet = SuiWallet(seed=TEST_ACCT_PHRASE)

# Read the contracts config (you can also specify filepath as an argument to read_json, by default it looks for rfq-contracts.json at root of working directory )
contracts_config = read_json()

# Initialize RFQContracts instance using the contract conffigs
rfq_contracts = RFQContracts(contracts_config)

# Initialize RFQClient
rfq_client = RFQClient(wallet=wallet, url=TEST_NETWORK, rfq_contracts=rfq_contracts)

#To create quote and sign it at the same time, use
quote, signature = rfq_client.create_and_sign_quote(
    vault="0x67399451f127894ee0f9ff7182cbe914008a0197a97b54e86226d1c33635c368",
    quote_id="quote-123",
    taker="0x67399451f127894ee0f9ff7182cbe914008a0197a97b54e86226d1c33635c368",
    token_in_amount=1000000000,
    token_out_amount=200000000,
    token_in_type="0x2::sui::SUI",
    token_out_type="0x2::example::TOKEN",
    created_at_utc_ms=1699765400,
    created_at_utc_ms=1698765400,
)

For a more detailed and complete guide on using the RFQClient in python please refer to our docs here

Updated about 1 month ago