Carbium for Wallet Developers

Wallet integrations fail when display data, quotes, signing, and transaction relay get treated as one feature. They are separate jobs with different trust boundaries.

Use Carbium as four wallet building blocks:

This page owns the wallet architecture. Use the linked product pages for exact endpoint reference, rate limits, and error triage.

Part of the Carbium Solana infrastructure stack.

The wallet shape to aim for

The strongest default is a backend-assisted wallet flow:

flowchart TD
    A["Wallet client<br/>user consent + signing"] --> B["Your backend<br/>keys, quotas, logs"]
    B --> C["Carbium Data<br/>token search + metadata + logos"]
    B --> D["Carbium Swap API<br/>quote + txn"]
    A --> E["Signed transaction"]
    E --> B
    B --> F["Carbium RPC<br/>submit + confirm"]

This keeps the user-facing wallet native while preventing two common production mistakes:

• exposing Carbium keys in browser bundles, mobile clients, screenshots, or public repos
• asking the client to coordinate quote errors, transaction signing, relay retries, and confirmation state by itself

Use Data for token display, not swap truth

Wallets need readable token rows before a user swaps. Use the Carbium Token Index API when your UI needs:

• search by symbol or name
• single-mint lookup
• batch hydration for token-account lists
• cached logo URLs for wallet rows, token pickers, and portfolio views

The live public base URL is:

https://tokens.carbium.io

Example search:

curl 'https://tokens.carbium.io/tokens?q=USDC&limit=3'

Example logo URL:

<img
  src="https://tokens.carbium.io/img/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  alt="USDC logo"
/>

Keep a local fallback icon. Solana token metadata is uneven, and nullable fields are normal. Carbium Data helps your wallet display tokens cleanly; Swap API route output is still the source for executable swap decisions.

Keep quote and signing boundaries explicit

For swaps, use your backend to request the executable quote from Carbium, then let the wallet sign the returned transaction payload.

const url = new URL("https://api.carbium.io/api/v2/quote");
url.searchParams.set("src_mint", "So11111111111111111111111111111111111111112");
url.searchParams.set("dst_mint", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
url.searchParams.set("amount_in", "1000000");
url.searchParams.set("slippage_bps", "50");
url.searchParams.set("user_account", walletAddress);

const quoteRes = await fetch(url, {
  headers: {
    "X-API-KEY": process.env.CARBIUM_API_KEY!,
    "Accept": "application/json",
  },
});

if (!quoteRes.ok) {
  throw new Error(`Quote failed with ${quoteRes.status}`);
}

const quote = await quoteRes.json();

if (!quote.txn) {
  throw new Error("Quote response did not include txn");
}

The client signs the transaction. It does not need either Carbium key:

import { VersionedTransaction } from "@solana/web3.js";

const unsignedTx = VersionedTransaction.deserialize(
  Buffer.from(quote.txn, "base64")
);

const signedTx = await wallet.signTransaction(unsignedTx);
const signedBase64 = Buffer.from(signedTx.serialize()).toString("base64");

After signing, send the payload back to your backend for relay and confirmation through Carbium RPC.

Relay signed transactions through your backend

Use Carbium RPC for submission and confirmation, but keep the RPC key server-side.

import { Connection, VersionedTransaction } from "@solana/web3.js";

const connection = new Connection(
  `https://rpc.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`,
  "confirmed"
);

async function relaySignedTransaction(signedBase64: string) {
  const signedTx = VersionedTransaction.deserialize(
    Buffer.from(signedBase64, "base64")
  );

  const signature = await connection.sendRawTransaction(
    signedTx.serialize(),
    { skipPreflight: false, maxRetries: 3 }
  );

  const confirmation = await connection.confirmTransaction(
    signature,
    "confirmed"
  );

  return { signature, confirmation };
}

Store the submitted signature with your app request ID before any retry logic runs. If the user refreshes or a worker restarts, check confirmation state before rebuilding or replaying the swap intent.

Where Gasless Swaps fit

Gasless Swaps are a wallet UX decision, not a universal default. Consider them when a user has the input token but no SOL for network fees, especially in:

• first-swap onboarding
• embedded wallets
• mobile flows where a separate SOL funding step would cause drop-off

Keep the normal quote -> sign -> relay path as your baseline. Add gasless behavior only in the branch where the user actually needs fee assistance, then log that branch separately so support can tell normal execution from gasless execution.

Production guardrails

Before shipping a wallet flow, verify:

• Carbium RPC and Swap API keys live only in backend env vars or a secret manager
• the wallet client receives token display data, quote results, and unsigned transactions, not Carbium credentials
• token metadata lookups tolerate missing logos, nullable descriptions, and unknown tags
• quote requests include user_account whenever the UI expects a signable transaction
• signed transactions are relayed once, persisted by signature, and confirmed before replay
• your UI separates quote failure, wallet rejection, RPC relay failure, and final on-chain failure

Use Carbium Auth Matrix for endpoint/key mapping, Quote to Swap Integration Guide for the full quote-to-confirm workflow, and Carbium Data API Calls for Token Index request shapes.

🔶

Building a Solana wallet with Carbium? Start with the backend boundary, then wire token display, quote construction, user signing, and RPC relay as separate steps. For platform access, start at carbium.io.