What is a Solana Trade API?

An API that prices a token trade and builds the transaction for it. On Solana the trade is a swap through on-chain liquidity: the API quotes a route, your wallet signs the transaction it returns, and the trade settles on chain. The Carbium Trade API is the Carbium Swap API, named for the job.

Free plan at 10 calls a second. 0.05% router fee per swap.

From quote to settled

Four steps, three of them calls to services.carbium.sh with one key. The fourth, signing, stays in your wallet.

  1. quote

    Quote the trade

    quote searches every venue family, multi-hop and split, and answers what goes in, what comes out, the floor after slippage, the route plan and a quoteId good for 30 seconds.

    Quote reference
  2. swap

    Build the transaction

    swap takes the quoteId and your wallet as user_pubkey, and answers one unsigned transaction: version 0 by default, version 1 when a route needs more room.

    Swap reference
  3. user_pubkey

    Sign in your wallet

    Sign as user_pubkey and change nothing in the transaction. The keys and the funds stay with you: Carbium never holds either.

    Signing rules
  4. sendTransaction

    Settle on chain

    Send through Carbium RPC with skipPreflight and confirm with getSignatureStatuses. The trade settles in that one transaction, router fee included.

    Carbium RPC

One API, many names

Search for a Solana Trade API, an Exchange API or a Settlement API and you are looking for the same few calls. Here is what each name means, and the part of Carbium that does it.

  • Swap API

    The name on the product

    A route quote and an unsigned swap transaction, as JSON-RPC methods on the same host and key as Carbium RPC. Venues, plans and the quick start are on its page.

    Carbium Swap API
  • Trade API

    The name for the job

    On Solana a token trade is a swap through on-chain liquidity. quote prices it, swap builds it, your wallet signs it, and it settles in one transaction.

    Quote reference
  • Settlement API

    Settled in one transaction

    Nothing settles off chain. The transaction your wallet signs moves the tokens and pays the router fee, and getSignatureStatuses tells you it landed.

    Swap reference
  • Exchange API

    Not an exchange

    Carbium has no order book, takes no deposits and holds no funds. It routes your swap across on-chain venues and hands you the transaction.

  • Quote API

    The quote method

    src_mint, dst_mint, amount_in and slippage_bps in; destAmountOut, minAmountOut, the route plan and a quoteId out. Amounts are strings in base units.

    Quote params and results
  • Aggregator API

    Many venues, one answer

    One quote searches 15 venue families, multi-hop and split, or only the venues you pin with dex. The full venue list is on the Swap API page.

    Supported venues
An Exchange API next to the Carbium Trade API
An Exchange APIThe Carbium Trade API
Who holds the fundsThe exchange, in your account thereYou, in your own wallet
What you sendAn orderA quote request, then a transaction you sign
What you get backAn order id and fillsOne unsigned transaction
Where it settlesOn the exchange's booksOn chain, in that transaction
The feeSet by the exchangeA 0.05% router fee inside the transaction
An Exchange API here means the order API of an exchange that holds customer funds; exchanges differ.

Shape the quote

  • Leave dex out to search every venue family, multi-hop and split
  • Pin up to 16 venue labels with dex for one hop on the venues you choose
  • Ask txVersion 1 for a route a version 0 transaction cannot fit
  • A partial fill answers partial: true, and swap builds the part that fills

Every amount is a decimal string in the token's smallest unit. Parse it with BigInt, never a JavaScript number.

Quote reference
quote.sh
# One quote: 0.01 SOL to USDC, 0.5% slippage
curl -s https://services.carbium.sh \
  -H "content-type: application/json" \
  -H "x-api-key: $CARBIUM_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"quote","params":{
    "src_mint":"So11111111111111111111111111111111111111112",
    "dst_mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount_in":"10000000","slippage_bps":50}}'

# The answer: srcAmountIn, destAmountOut, minAmountOut,
# routePlan (one entry per leg), quoteId (good for 30 s), platformFee
From the quote section of carbium.sh's reference. Quotes are JSON-RPC: there is no REST path, the method goes in the body.

One trade, start to settled

Quote, build for your wallet, sign, send, confirm. One key covers every call.

  1. Quote

    Call quote with src_mint, dst_mint, amount_in and slippage_bps. Show destAmountOut and minAmountOut as they come: the router fee is already inside both.

  2. Build within 30 seconds

    Call swap with the quoteId as quote_id and your wallet as user_pubkey. A quoteId is good for 30 seconds; after that, quote again.

  3. Sign, change nothing

    Sign as user_pubkey only. A transaction that is changed after it is built is not the trade that was quoted.

  4. Send once, confirm by status

    Send with skipPreflight and read getSignatureStatuses. On an expired quote or a slippage failure (Custom:6004), quote again instead of resending.

trade.ts
// Quote, build, sign, send, confirm: one trade, settled on chain
const KEY = process.env.CARBIUM_KEY;
const call = async (method, params) => {
  const res = await fetch("https://services.carbium.sh", { method: "POST",
    headers: { "content-type": "application/json", "x-api-key": KEY },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
  const { result, error } = await res.json();
  if (error) throw new Error(method + " failed: " + error.message);
  return result;
};

const quote = await call("quote", { src_mint: SOL, dst_mint: USDC,
  amount_in: "10000000", slippage_bps: 50 });
const { transaction } = await call("swap", { quote_id: quote.quoteId,
  user_pubkey: wallet.publicKey.toBase58() });

const tx = VersionedTransaction.deserialize(Buffer.from(transaction, "base64"));
tx.sign([wallet]); // sign as user_pubkey; change nothing
const sig = await call("sendTransaction", [Buffer.from(tx.serialize()).toString("base64"),
  { encoding: "base64", skipPreflight: true, maxRetries: 0 }]);
const { value } = await call("getSignatureStatuses", [[sig]]);
// value[0].confirmationStatus: processed, confirmed, then finalized
Shortened from the quote and swap sections of carbium.sh's reference.

The router fee

Each swap pays a 0.05% router fee, inside the router instruction of the transaction you sign; there is no separate transfer. Quotes add no fee and spend no RPC credits.

Plans and pricing

What breaks in a trade

Most failed trades come from the same few mistakes, and each has a fix in the reference.

  • Swap within 30 seconds

    A quoteId lasts 30 seconds and can be dropped sooner under load. Build right after you quote, or quote again.

    Swap reference
  • Never change the transaction

    Sign it as user_pubkey and send it as built. An edited transaction is not the trade that was quoted.

    Signing rules
  • Never auto-retry a send

    Read getSignatureStatuses first: the first send may have landed. On a slippage failure (Custom:6004), quote again.

    Sending and simulating
  • Do not take the fee twice

    The router fee is already inside destAmountOut and minAmountOut. Show and check those figures as they are.

    The router fee
  • Parse amounts with BigInt

    Amounts are decimal strings in base units. A JavaScript number loses digits above 2^53.

    Quote results
  • Read HTTP 200 errors

    No route or no live pool can come back as HTTP 200 with an error. Check error.code before you read the result.

    Errors and actions

Questions

The reference on carbium.sh covers every param and error. For anything else, talk to the team on the Carbium Discord.

Quote reference, on carbium.sh

What is a Solana Trade API?

An API that prices a token trade and builds the transaction for it. On Solana a trade is a swap through on-chain liquidity, so a Trade API quotes a route and returns a transaction your wallet signs. The Carbium Trade API does both, as the quote and swap methods.

Is the Carbium Trade API the same as the Carbium Swap API?

Yes. It is the same quote and swap methods, on the same key and the same plans. This page explains it by the job; venues, plans and the quick start are on the Carbium Swap API page.

Carbium Swap API

Is the Carbium Trade API an Exchange API?

No. Carbium is not an exchange: it has no order book, takes no deposits and holds no funds. It routes a swap across on-chain venues and returns an unsigned transaction, and the trade settles on chain when your wallet signs and sends it.

What is a Settlement API on Solana?

The part of a flow that turns a quote into a final on-chain result. With Carbium, swap builds the transaction, your wallet signs it, Carbium RPC sends it, and getSignatureStatuses confirms it. The tokens move and the router fee is paid in that one transaction.

Swap reference

When is a trade on Solana final?

getSignatureStatuses answers each signature's confirmationStatus: processed, then confirmed, then finalized, with err when it failed. Processed can still roll back, so tell users a trade is done at the level your app trusts.

Commitment levels

Does Carbium hold my funds or keys during a trade?

No. swap returns an unsigned transaction built for your wallet's public key. You sign it with your own key, and it settles on chain. Carbium never receives the key or holds the tokens.

Can I limit a quote to certain venues?

Yes. Pass dex with one venue label or up to 16, for one hop from src_mint to dst_mint on those venues. A pair with no such route answers no_route_in_pinned_dex rather than a route on another venue.

Venue labels

Can I get token prices from the same API?

Yes. The prices method answers USD prices and liquidity for up to 64 mints a call, from a table cached for 30 seconds. Poll it on a timer; each call counts as one call against the plan.

The prices method

Make the first trade on the free plan

The Free plan answers 10 calls a second, with the same API and the same 0.05% router fee as every plan. Venues, plans and the quick start are on the Carbium Swap API page.

Plans and pricing