Swap

Use this page when you are maintaining or testing the older Carbium Swap API surface:

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

For most new integrations, start with Q1 instead. Q1 uses GET /api/v2/quote and can return txn directly when user_account is provided. This page stays focused on the v1 provider-specific swap builder.

Part of the Carbium Solana infrastructure stack.

What this endpoint does

GET /api/v1/swap builds a base64-encoded Solana transaction for a requested token swap. Your app still owns the signing and submission path.

Use this endpoint when you need the documented v1 fields such as:

a required provider
optional pool selection
custom fee receiver settings
priority-fee settings
mevSafe or gasless execution flags

If your integration only needs the current quote -> executable transaction path, use Q1 instead of recreating this older flow.

Request shape

Method: GET

URL:

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

Headers:

X-API-KEY: YOUR_API_KEY
accept: text/plain

Parameter	Required	Meaning
`owner`	Yes	Wallet address that will own/sign the swap transaction
`fromMint`	Yes	Input token mint
`toMint`	Yes	Output token mint
`amount`	Yes	Raw input amount in smallest units
`slippage`	Yes	Slippage tolerance in basis points
`provider`	Yes	DEX/provider route to use
`pool`	No	Custom pool address for the route
`feeLamports`	No	Custom fee amount in lamports
`feeReceiver`	No	Account that receives the custom fee when `feeLamports` is used
`priorityMicroLamports`	No	Compute-unit price for priority fees
`mevSafe`	No	Adds a Jito-tip instruction when set to `true`
`gasless`	No	Requests gasless handling where the documented route supports it

📘
Keep v1 parameter names together. This endpoint expects fromMint, toMint, amount, slippage, and provider, not Q1 fields like src_mint, dst_mint, amount_in, or slippage_bps.

Minimal request

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 request asks Carbium to build a SOL -> USDC swap transaction through the documented raydium provider path.

Response shape

The API reference documents a successful response as a transaction payload. In guide code, treat the returned transaction as a build artifact that still needs signing.

Common fields:

Field	Meaning
`success`	Whether Carbium built the transaction payload
`data`	Base64 transaction payload, or an object containing transaction data depending on the response path
`base64Transaction`	Base64 transaction field shown by older guide examples
`signers`	Additional signer information when returned

Example guide shape:

{
  "success": true,
  "data": {
    "base64Transaction": "AQAAAA...",
    "signers": []
  }
}

Do not treat a successful build response as an on-chain swap. The transaction still has to be deserialized, signed, submitted, and confirmed.

Provider and optional execution fields

The API reference currently lists these provider values:

Provider value
`meteora`
`orca`
`raydium`
`meteora-dlmm`
`pump-fun`
`moonshot`
`stabble`
`printdex`
`raydium-cpmm`
`goosefx`

Only add optional fields when your integration actually owns the behavior they change.

Option	Use when
`pool`	You need a specific pool rather than provider-level routing
`feeLamports` + `feeReceiver`	Your app collects a custom fee and can validate the receiver account
`priorityMicroLamports`	You intentionally set priority-fee policy for this transaction
`mevSafe`	You want the documented Jito-tip path on this `v1` surface
`gasless`	Your route matches the documented gasless constraints

If you are unsure, keep the minimal request first and add optional behavior one field at a time.

Common failure modes

Status or symptom	Likely cause	First fix
`401`	Missing API key	Send `X-API-KEY` with the Swap API key
`400` with `No pool found`	The selected provider or pool cannot serve the requested pair	Remove `pool`, change `provider`, or verify the pair/liquidity path
Transaction payload returned but signing fails	The build step succeeded; the failure moved to signer setup	Check wallet ownership, signer type, and transaction deserialization
Transaction sends but does not confirm	The failure moved to RPC submission or on-chain execution	Debug the send/confirm path, not this build endpoint

Use Swap API Errors Reference for pre-sign failures. Use Executing Swaps when you need the signing and confirmation workflow.

When to use Q1 instead

Choose Q1 when you want the current Carbium quote flow:

GET /api/v2/quote
src_mint, dst_mint, amount_in, slippage_bps
optional user_account
txn returned from the quote response when an executable transaction is requested

Choose this v1 Swap page when you specifically need the older provider-specific GET /api/v1/swap controls.

🔶
For new builds, start with Q1. For existing v1 swap flows, keep this page next to API Commands and the Get / Swap reference. Platform access starts at carbium.io.