Carbium Cookbook: Runnable RPC and Swap API Recipes
Nine runnable Node.js recipes for Carbium Solana RPC and Swap API integrations, continuously verified against live endpoints in CI.
The Carbium Cookbook is a living repository of nine runnable Node.js recipes for common Carbium RPC, streaming, and Swap API tasks. Each recipe is linked to its source file and checked by the repository’s verification workflow so you can start from working integration code rather than an isolated snippet.
Quick start
Clone the repository, install its dependencies, add your own keys to its ignored .env file, then run a recipe:
git clone https://github.com/Ukkometa/carbium-cookbook
cd carbium-cookbook
npm install
cp .env.example .env
npm run rpc:first-call
The repository documents the current Node.js requirement and the available npm scripts. Keep keys out of source control and never paste a live key into a support request, issue, or log.
Carbium RPC endpoint URL and authentication
The RPC recipes use https://rpc-service.carbium.io/?apiKey=<your-rpc-key>. The apiKey belongs in the URL query string for RPC calls.
| Product | Recipe endpoint | Authentication |
|---|---|---|
| Carbium RPC | https://rpc-service.carbium.io/ |
?apiKey=<RPC key> query parameter |
| Carbium Swap API | https://api.carbium.io/api/v2 |
X-API-KEY: <Swap key> request header |
These are separate keys with separate placements. Treat the RPC connection URL as sensitive because it contains the query parameter. Build it at runtime and log only its host:
const rpc = `https://rpc-service.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`;
console.log(new URL(rpc).host); // rpc-service.carbium.io
For the full authentication matrix and key-placement guidance, see Carbium Auth Matrix.
Connect with @solana/web3.js
Use the RPC URL with a standard Connection:
import { Connection } from "@solana/web3.js";
const rpc = `https://rpc-service.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`;
const connection = new Connection(rpc, "confirmed");
const slot = await connection.getSlot();
console.log(slot);
The complete rpc-first-call.mjs recipe also reports the call’s round-trip time. For a browser-free first endpoint check, start with Your First Test Call.
The recipes
RPC recipes
| Recipe | What it demonstrates |
|---|---|
| rpc-first-call.mjs | getSlot and a round-trip measurement |
| rpc-account-balance.mjs | SOL balance, account owner, and data size |
| rpc-latest-blockhash.mjs | Latest blockhash and blocks until expiry |
| rpc-token-accounts.mjs | Parsed SPL token accounts for a wallet |
| rpc-priority-fees.mjs | Recent priority-fee observations |
Streaming recipe
| Recipe | What it demonstrates |
|---|---|
| stream-transactions.mjs | A WebSocket transactionSubscribe client filtered by account |
The streaming recipe uses a WebSocket connection to wss://grpc.carbium.io/?apiKey=<your-rpc-key> and sends transactionSubscribe. It is a Yellowstone-style streaming recipe, not a native gRPC/HTTP2 setup guide. If you use standard Solana PubSub method names such as slotSubscribe, consult the recipe and Carbium gRPC for the documented subscription model.
Swap API recipes
| Recipe | What it demonstrates |
|---|---|
| swap-quote.mjs | A read-only Swap API quote with slippage and price impact |
| swap-quote-usd.mjs | USD value for both sides of a swap |
| swap-cycle-scanner.mjs | Same-mint cycle screening with configurable transaction-cost assumptions |
Getting a quote is a read-only request: it does not sign or broadcast a transaction. The cycle scanner is an investigative tool, not trading advice or an execution engine; review price impact, fees, slippage, competition, and execution risk before acting on any quote.
Move from a quote to a Swap API integration
Use the cookbook’s quote recipes to validate request shape and response handling in a small environment first. When you are ready to carry a quote through an application integration, continue with Quote to Swap Integration Guide. The Carbium Swap API developer hub is the canonical API integration surface; use Swap API Errors Reference when an API response needs troubleshooting.
Troubleshooting
405 Method Not Allowed from rpc.carbium.io
JSON-RPC calls belong on https://rpc-service.carbium.io/?apiKey=<your-rpc-key>. The cookbook’s RPC first-call recipe uses that endpoint.
403 {"error":"API Key missing"}
The RPC key is missing from the apiKey query parameter. An empty ?apiKey= is also missing.
401 {"error":"API key missing"} from api.carbium.io
The Swap API expects its own key in the X-API-KEY request header. Do not substitute an RPC key for the Swap API key.
-32010: <program> excluded from account secondary indexes
This can occur when getProgramAccounts targets a program outside the configured account secondary indexes. For wallet token-account discovery, use the cookbook’s rpc-token-accounts.mjs approach based on getParsedTokenAccountsByOwner.
StructError: Expected a Buffer instance, but received: [object Object]
Use getParsedTokenAccountsByOwner for parsed token-account results rather than requesting parsed encoding from getTokenAccountsByOwner. The complete working call is in rpc-token-accounts.mjs.
SyntaxError: Unexpected token '<' when listing token accounts
This means the client received HTML rather than the JSON it expected. Narrow the request by mint where possible and use the cookbook recipe as the reference implementation. If the issue persists, capture the request shape without credentials and contact Carbium support.
Mini FAQ
Do I need one API key or two?
Two: an RPC key in the endpoint query parameter and a Swap API key in the X-API-KEY header. See Carbium Auth Matrix for the full mapping.
Why does slotSubscribe fail on the WebSocket endpoint?
The cookbook streaming example is built around transactionSubscribe, not the standard Solana PubSub method. Use stream-transactions.mjs as the working request shape.
Is getting a swap quote a transaction?
No. The cookbook’s quote recipes use read-only requests. They do not sign or broadcast a transaction.
Why is the streaming host called grpc if I connect over WebSocket?
The documented recipe uses a WebSocket client and a Yellowstone-style streaming payload. Use the WebSocket endpoint and recipe; do not treat this guide as native gRPC/HTTP2 connection instructions.
Verification and source of truth
The repository’s verification workflow runs the recipes on pushes to main and on a scheduled Monday run. Review the workflow status and source files before depending on a recipe in production; the repository is the living implementation source, while this page is the canonical Docs entry point and troubleshooting map.