Swap API Request Families

Most Carbium Swap API mistakes are not routing mistakes. They are request-family mistakes.

Use this page when you are deciding whether an integration should call the current Q1 flow or one of the older v1 quote and swap paths. It gives you the map before you copy parameters into production code.

Part of the Carbium Solana infrastructure stack.

The short rule

Pick one request family for one integration path.

If the endpoint path is v2, think Q1. If the endpoint path is v1, think older quote, comparison, swap-build, or bundle handoff.

📘

Changing parameter names is not a migration by itself. A Q1 request and a v1 swap request answer different integration questions.

Use Q1 for new executable quote flows

Start with Q1 when your product needs the current Carbium quote flow and may want an executable transaction payload from the quote response.

GET https://api.carbium.io/api/v2/quote

Minimal quote-only shape:

curl --request GET \
  --url 'https://api.carbium.io/api/v2/quote?src_mint=So11111111111111111111111111111111111111112&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount_in=1000000&slippage_bps=50' \
  --header 'X-API-KEY: YOUR_API_KEY'

Executable-transaction shape:

curl --request GET \
  --url 'https://api.carbium.io/api/v2/quote?src_mint=So11111111111111111111111111111111111111112&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount_in=1000000&slippage_bps=50&user_account=YOUR_WALLET' \
  --header 'X-API-KEY: YOUR_API_KEY'

The practical distinction is user_account.

Use Q1 for the detailed request and response shape. Use Executing Swaps after a transaction payload exists.

Use v1 Quote for provider-specific quote checks

Use the older Quote path when you are maintaining a provider-specific quote integration.

GET https://api.carbium.io/api/v1/quote

curl --request GET \
  --url 'https://api.carbium.io/api/v1/quote?fromMint=So11111111111111111111111111111111111111112&toMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000&slippage=100&provider=raydium' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'accept: text/plain'

This path is useful when a legacy or provider-pinned app already owns the v1 parameter style. It is not the best starting point for new executable-quote builds.

Use Quote for the full older quote guide.

Use All Quote for provider comparison

Use All Quote when the job is comparison across documented providers, not transaction construction.

GET https://api.carbium.io/api/v1/quote/all

curl --request GET \
  --url 'https://api.carbium.io/api/v1/quote/all?fromMint=So11111111111111111111111111111111111111112&toMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000&slippage=100' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'accept: text/plain'

This path can show mixed provider results. One provider missing a route is not the same thing as the whole request failing.

Use All Quote when your app needs provider-level quote comparison or route-miss diagnostics.

Use v1 Swap for older transaction-build controls

Use the older Swap path when you specifically need the documented v1 swap-build controls.

GET https://api.carbium.io/api/v1/swap

curl --request GET \
  --url 'https://api.carbium.io/api/v1/swap?owner=YOUR_WALLET&fromMint=So11111111111111111111111111111111111111112&toMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000&slippage=100&provider=raydium' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'accept: text/plain'

This path is for building a transaction payload. It does not sign for your user and it does not prove the swap landed on-chain.

Use Swap when your app depends on v1 fields such as provider, optional pool selection, custom fee settings, priority-fee settings, mevSafe, or gasless.

Use bundle only after signing

The bundle path is not a quote path and not a signer.

GET https://api.carbium.io/api/v1/swap/bundle

Use it only when your integration already has a signed transaction payload and intentionally wants the documented bundle handoff.

Use TXN Bundle for the focused bundle handoff guide.

Common migration traps

Trap 1: renaming fields without changing the flow

Q1 does not use fromMint, but changing fromMint to src_mint is only one part of a move. You also need to confirm whether your app expects quote-only data or a txn field.

Trap 2: treating v1 Swap as the same as Q1

GET /api/v1/swap is an older transaction-build path with provider-oriented controls. Q1 is the current executable quote flow. They can both participate in swap integrations, but they should not be blended inside one request.

Trap 3: debugging auth as a route issue

A request that fails before routing is not a liquidity problem. Public checks on api.carbium.io return 401 when X-API-KEY is missing and 403 when an invalid key is sent to Q1.

Trap 4: expecting every successful API response to be final execution

Quote data, transaction payload construction, wallet signing, RPC submission, and confirmation are separate stages. Keep logs and errors labeled by stage.

Decision checklist

🔶

For most new integrations, start with Q1, keep the Swap API key on your backend, and move into signing and RPC confirmation only after the quote response is internally consistent.