Execute a swap - Bloom API

curl --request POST \
  --url https://eu.solana.bloombot.app/api/v1/swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "side": "Buy",
  "wallets": [
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "amount": "0.1"
    }
  ],
  "slippage": 10,
  "priority_fee": 0.001,
  "processor_tip": 0.0001,
  "anti_mev": false,
  "auto_tip": false
}
'

{
  "success": true,
  "data": {
    "order_id": "<string>",
    "signatures": [
      "<string>"
    ],
    "skipped": false
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

POST

api

swap

curl --request POST \
  --url https://eu.solana.bloombot.app/api/v1/swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "side": "Buy",
  "wallets": [
    {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "amount": "0.1"
    }
  ],
  "slippage": 10,
  "priority_fee": 0.001,
  "processor_tip": 0.0001,
  "anti_mev": false,
  "auto_tip": false
}
'

{
  "success": true,
  "data": {
    "order_id": "<string>",
    "signatures": [
      "<string>"
    ],
    "skipped": false
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>"
  }
}

wallets is optional. Omit it (or pass null), set a top-level amount, and the swap runs on every wallet with spot trading enabled in Bloom — the same wallets the bot and extension trade from. To name wallets explicitly, list them with GET /api/v1/wallets first. An empty wallets array is an error (NO_WALLETS), not a fallback.

auto_orders has three states. Omitted or null applies the Spot strategy saved in Bloom Manager; an empty array [] attaches no auto-orders at all; a non-empty array uses exactly those orders. See the Auto-orders guide for the full field reference, the target_value table, and examples.

Building a bot that might see the same token twice? Set skip_if_bought on a Buy and the request becomes a no-op if any wallet on your account already bought that token. A skipped request is a 200 with data.skipped: true and no signatures — not an error.

Building on Bloom for other traders? Set builder_address and builder_fee_bps (1–100) together and that wallet earns a share of the swap, paid on top of Bloom’s fee in the same transaction. See Builder fees.

Authorizations

Authorization

string

header

required

Your Bloom API key, e.g. Authorization: Bearer blm_sol_live_…. Create one in Bloom Manager → Manage API Keys.

Body

application/json

address

string

required

Token mint address or pool ID.

side

enum<string>

required

Available options:

Buy,

Sell

priority_fee

number

required

Priority fee. Denominated in SOL on the Solana host and in gwei on the EVM host — see Fee denomination.

processor_tip

number

required

Processor tip; ignored when auto_tip is true. Denominated in SOL on the Solana host and in the chain's native asset on the EVM host.

slippage

number

required

Slippage tolerance as a percentage, e.g. 10 = 10%.

anti_mev

boolean

required

auto_tip

boolean

required

When true, the server sets the priority fee and processor tip for you.

chain

enum<string>

EVM host only. The chain to trade on, matched case-insensitively. Optional — when omitted, the token address is resolved across the supported chains automatically. Pass it explicitly to pin the lookup to one chain. An unrecognised value fails with INVALID_REQUEST. Not used on the Solana host. See Chains and quote assets.

Available options:

eth,

bsc,

base,

rbh,

arc

sell_mode

enum<string>

default:percent

For a Sell, how each wallet's amount is interpreted: percent (1-100 of holdings, the default) or tokens (absolute token quantity). An over-amount in tokens mode sells the full balance. Ignored for a Buy. tokens is Solana-only — the EVM host rejects it with INVALID_REQUEST.

Available options:

percent,

tokens

skip_if_bought

boolean

default:false

When true, skip the whole swap if any wallet on your account has already bought this token — for a bot that may see the same token twice and must not double-buy. The check runs against your Bloom trade history for the token, so it also covers buys placed from the bot, the extension, or the manager, not just from this API.

A skipped request is not an error: it returns 200 with data.skipped: true and an empty signatures. It still consumes one unit of rate-limit budget.

Buys only — ignored for a Sell, where it would mean "refuse to sell what you hold".

max_tax

number

EVM host only. Maximum token buy/sell tax you will accept, as a percentage (5 = 5%). The token's tax is probed before execution; a trade on a token whose tax exceeds the cap is rejected with TAX_OUT_OF_RANGE. An explicit 0 means "tax-free tokens only". Omitted = no cap: the tax check does not run. Not used on the Solana host.

The tax check is best-effort and not guaranteed to catch every case: the tax actually applied at execution can differ from the probed value. Trading taxed or malicious tokens is at your own risk; Bloom is not responsible for losses caused by token taxes or token contract behaviour.

Required range: 0 <= x <= 100

amount

string

Default amount for every wallet the swap runs on, as a decimal string in the same units as wallets[].amount (quote asset to spend on a Buy; percent of holdings or token quantity on a Sell, per sell_mode). Required when wallets is omitted — each default wallet trades this amount. When wallets is given, it is the fallback for any entry that leaves its own amount unset.

wallets

object[]

Wallets to swap from; each must belong to your account. Optional: omit it (or pass null) and the swap runs on every wallet with spot trading enabled in Bloom — the same set the Bloom bot and extension trade from — each spending the top-level amount. List them with GET /api/v1/wallets (spot_active: true). An empty array is rejected with NO_WALLETS; it never falls back to the defaults.

Minimum array length: 1

Show child attributes

auto_orders

object[]

Attach take-profit / stop-loss / trailing / time / dev-sell exits to this swap (up to 20; any beyond 20 are dropped). See the Auto-orders guide for the full field reference, the target_value table, and examples.

Omitted or null: the swap uses the auto-orders of the Spot strategy saved in Bloom Manager, exactly as a trade from the bot or extension would. Empty array []: no auto-orders at all, even if a strategy is saved. Non-empty: exactly the orders given; the saved strategy is not merged in.

Maximum array length: 20

Show child attributes

quote_asset

enum<string>

Quote asset to trade against — what a Buy spends, and the unit of wallets[].amount. Omit it to use the chain's native token.

Each chain's native token is named by its own symbol: SOL on the Solana host, and on EVM ETH (eth, base, rbh), BNB (bsc) or USDC (arc, whose native token is USDC).

Support is validated per chain — eth USDC/USDT, bsc USD1/USDC/USDT, base USDC, rbh USDG, arc native only, Solana USDC/USD1. An asset the chain does not support is rejected with INVALID_REQUEST, and the error lists the valid set. See Chains and quote assets.

Available options:

SOL,

ETH,

BNB,

USDC,

USDT,

USD1,

USDG

min_liquidity

number

Pool liquidity bounds in USD.

max_liquidity

number

Pool liquidity bounds in USD.

min_market_cap

number

Token market-cap bounds in USD.

max_market_cap

number

Token market-cap bounds in USD.

builder_address

string

Builder fee: a wallet that earns a share of this trade, paid on top of Bloom's fee as a separate transfer in the same transaction, in the asset the trade settles in. A Buy pays it on the amount spent, a Sell on the proceeds. An address on the chain being traded — base58 on the Solana host, 0x… on the EVM host.

Sent together with builder_fee_bps, or not at all — one without the other is rejected with INVALID_REQUEST, never half-applied. Omit both for a swap with no builder fee. See Builder fees.

builder_fee_bps

integer

The builder's share in basis points, 1–100 (100 = 1%). Required with builder_address; a value outside the range is rejected with INVALID_REQUEST.

Required range: 1 <= x <= 100

Response

Swap accepted.

success

boolean

required

Example:

true

data

object

required

Show child attributes