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.
quoteQuote 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 referenceswapBuild 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 referenceuser_pubkeySign 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 rulessendTransactionSettle 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 APITrade 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 referenceSettlement 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 referenceExchange 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 resultsAggregator 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 | The Carbium Trade API | |
|---|---|---|
| Who holds the funds | The exchange, in your account there | You, in your own wallet |
| What you send | An order | A quote request, then a transaction you sign |
| What you get back | An order id and fills | One unsigned transaction |
| Where it settles | On the exchange's books | On chain, in that transaction |
| The fee | Set by the exchange | A 0.05% router fee inside the transaction |
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# 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
One trade, start to settled
Quote, build for your wallet, sign, send, confirm. One key covers every call.
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.
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.
Sign, change nothing
Sign as user_pubkey only. A transaction that is changed after it is built is not the trade that was quoted.
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.
// 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
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 pricingWhat 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 referenceNever change the transaction
Sign it as user_pubkey and send it as built. An edited transaction is not the trade that was quoted.
Signing rulesNever auto-retry a send
Read getSignatureStatuses first: the first send may have landed. On a slippage failure (Custom:6004), quote again.
Sending and simulatingDo not take the fee twice
The router fee is already inside destAmountOut and minAmountOut. Show and check those figures as they are.
The router feeParse amounts with BigInt
Amounts are decimal strings in base units. A JavaScript number loses digits above 2^53.
Quote resultsRead 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
Read further
The reference for each call, and two guides on what happens around a trade.
Quote and swap reference
Every param, result field and error, with the action to take, on carbium.sh.
When a trade is final
Processed, confirmed and finalized: what each commitment level means before you tell a user it is done.
Gasless token swaps
Let users swap without holding SOL for the network fee, in the Carbium docs.
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.shWhat 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 APIIs 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 referenceWhen 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 levelsDoes 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 labelsCan 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 methodMake 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