carbium

Carbium — 全栈 Solana 基础设施

Carbium 是基于裸金属服务器的 Solana 基础设施，由瑞士团队设计，不经由云服务中间商。一个平台覆盖完整的交易生命周期。

概览

产品	端点	用途
RPC	https://rpc.carbium.io	标准 JSON-RPC，用于读取、写入和订阅
标准 WebSocket	wss://wss-rpc.carbium.io	原生 Solana pubsub（账户变更、slot、日志、签名）
gRPC / Stream	wss://grpc.carbium.io	Yellowstone Full Block 流式传输（延迟约 22ms）
Swap API	https://api.carbium.io	由 CQ1 引擎驱动的 DEX 聚合与执行
DEX 应用	https://app.carbium.io	面向用户的交易界面
文档	https://docs.carbium.io	完整文档

主要优势：

• 通过采用二进制原生状态的 CQ1 路由引擎，实现亚毫秒级 DEX 报价
• 约 22ms 的 Full Block gRPC — 原子、完整的区块（无需重新组装 shred）
• 免 Gas 兑换 — 用户无需持有 SOL 即可交易
• MEV 保护 — Swap API 内置 Jito 打包
• 瑞士裸金属服务器 — RPC 延迟低于 50ms，正常运行时间达 99.99%

---

何时使用此技能

我想要……	使用	所需密钥
读取账户数据 / 余额	RPC	RPC 密钥
发送交易	RPC	RPC 密钥
实时监控钱包	标准 WebSocket	RPC 密钥
无需轮询即可确认交易	标准 WebSocket	RPC 密钥
监控程序账户变更	标准 WebSocket	RPC 密钥
构建钱包应用	RPC + Swap API	两者都需要
获取代币兑换报价	Swap API	API 密钥
以编程方式执行兑换	Swap API	API 密钥
使用 Jito 打包执行兑换	Swap API（bundle 端点）	API 密钥
比较所有 DEX 提供方的报价	Swap API（quote/all）	API 密钥
用户无需持有 SOL 即可兑换	Swap API（gasless 标志）	API 密钥
抢购 pump.fun 代币（毕业前）	gRPC + 直接 bonding curve 交易	RPC 密钥（Business 及以上）
实时响应链上事件	gRPC（流式传输）	RPC 密钥（Business 及以上）
为某个程序索引交易	gRPC（流式传输）	RPC 密钥（Business 及以上）
构建套利 / MEV 机器人	gRPC + Swap API	两者都需要

---

快速开始

1. 获取 API 密钥

产品	注册	备注
RPC + gRPC + WebSocket	rpc.carbium.io/signup	一个密钥适用于 RPC、WebSocket 和 gRPC
Swap API	api.carbium.io/login	单独的密钥，免费账户，即时开通

目前尚不支持以编程方式配置密钥。必须通过控制台创建密钥。

2. 设置环境变量

export CARBIUM_RPC_KEY="your-rpc-key"
export CARBIUM_API_KEY="your-swap-api-key"

3. 安全规则（必须遵守）

• 切勿在前端 / 客户端代码中嵌入密钥
• 切勿将密钥提交到版本控制系统
• 使用环境变量：CARBIUM_RPC_KEY、CARBIUM_API_KEY
• 如果密钥泄露，请立即轮换
• 密钥只能保存在服务端

---

定价层级

层级	价格	每月额度	最大 RPS	gRPC	WebSocket
Free	$0	500K	10	否	是
Developer	$32/mo	10M	50	否	是
Business	$320/mo	100M	200	是	是
Professional	$640/mo	200M	500	是	是

gRPC 流式传输要求使用 Business 层级或更高级别。

---

RPC

标准 Solana JSON-RPC。可使用任何 Solana SDK：@solana/web3.js、solana-py、solana Rust crate。

端点：

https://rpc.carbium.io/?apiKey=YOUR_RPC_KEY

TypeScript

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

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

// Read balance
const pubkey = new PublicKey("YOUR_WALLET_ADDRESS");
const balance = await connection.getBalance(pubkey);
console.log(`Balance: ${balance / LAMPORTS_PER_SOL} SOL`);

// Send transaction
const sig = await connection.sendRawTransaction(transaction.serialize(), {
  skipPreflight: false,
  maxRetries: 3,
});
await connection.confirmTransaction(sig, "confirmed");

Python

from solana.rpc.api import Client
from solders.pubkey import Pubkey
import os

rpc = Client(f"https://rpc.carbium.io/?apiKey={os.environ['CARBIUM_RPC_KEY']}")
pubkey = Pubkey.from_string("YOUR_WALLET_ADDRESS")
resp = rpc.get_balance(pubkey)
print(f"Balance: {resp.value / 1e9} SOL")

Rust

use solana_client::rpc_client::RpcClient;
use solana_sdk::pubkey::Pubkey;
use std::str::FromStr;

let url = format!(
    "https://rpc.carbium.io/?apiKey={}",
    std::env::var("CARBIUM_RPC_KEY").unwrap()
);
let client = RpcClient::new(url);
let pubkey = Pubkey::from_str("YOUR_WALLET_ADDRESS").unwrap();
let balance = client.get_balance(&pubkey).unwrap();
println!("Balance: {} lamports", balance);

Commitment 级别

级别	速度	保障	适用场景
processed	约 400ms	可能回滚	价格馈送、低风险 UX
confirmed	约 2s	获得超级多数投票	默认 — 最佳平衡
finalized	约 32s	完全最终确认	不可逆确认、高价值操作

标准 WebSocket（Solana Pubsub）

原生 Solana WebSocket Pubsub——任何为 Solana WebSocket 构建的 SDK 都可直接使用，无需修改。

端点：

wss://wss-rpc.carbium.io/?apiKey=YOUR_RPC_KEY

身份验证：使用与查询参数相同的 RPC 密钥。所有套餐均可使用（建议生产环境使用 Developer 套餐或更高套餐）。

WSS 与 gRPC——该如何选择

	标准 WSS	gRPC / Yellowstone
协议	基于 WebSocket 的 JSON-RPC	基于 WebSocket（或 HTTP/2）的二进制 protobuf
可获取内容	账户变更、槽位更新、日志、签名	完整原子区块、所有交易
SDK 支持	任意 Solana SDK（@solana/web3.js、solana-py）	Yellowstone 客户端，或使用 JSON 筛选器的原始 WS
延迟	订阅确认低于 100ms	完整区块传输约需 22ms
所需套餐	Developer+	Business+
最适合	钱包、dApp、特定账户监控	MEV 机器人、索引器、完整区块处理

**经验法则：**监控特定账户或签名 → 使用 WSS。处理所有交易或需要完整区块数据 → 使用 gRPC。

订阅方法

方法	推送内容	典型用例
slotSubscribe	新槽位编号	区块时钟、存活检查
rootSubscribe	已最终确认的槽位	最终性跟踪
accountSubscribe	账户数据变更	钱包余额更新、PDA 状态变更
programSubscribe	程序拥有的所有账户	DEX 池状态、质押更新
signatureSubscribe	交易确认状态	实时确认已发送的交易
logsSubscribe	符合筛选条件的交易日志	程序事件监控
blockSubscribe	完整区块数据	区块浏览器、索引器
slotsUpdatesSubscribe	详细的槽位生命周期事件	高级计时、验证器监控
voteSubscribe	投票交易	验证器监控

TypeScript——监控钱包

import WebSocket from "ws";

const ws = new WebSocket(
  `wss://wss-rpc.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "accountSubscribe",
    params: [
      "YOUR_WALLET_ADDRESS",
      { encoding: "base64", commitment: "confirmed" },
    ],
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.result !== undefined) {
    console.log(`Subscribed, id: ${msg.result}`);
    return;
  }
  if (msg.method === "accountNotification") {
    const { lamports } = msg.params.result.value;
    console.log(`Balance changed: ${lamports / 1e9} SOL`);
  }
});

TypeScript——通过 WSS 确认交易

ws.send(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "signatureSubscribe",
  params: ["YOUR_TX_SIGNATURE", { commitment: "confirmed" }],
}));

// signatureSubscribe auto-unsubscribes after first notification

TypeScript——串流传输程序日志

ws.send(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "logsSubscribe",
  params: [
    { mentions: ["PROGRAM_ID"] },
    { commitment: "confirmed" },
  ],
}));

使用 @solana/web3.js（推荐）

Connection 类原生支持订阅：

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

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

// Account subscription
connection.onAccountChange(
  new PublicKey("YOUR_WALLET"),
  (info, ctx) => console.log(`Balance: ${info.lamports / 1e9} SOL at slot ${ctx.slot}`),
  "confirmed"
);

// Slot subscription
connection.onSlotChange((slotInfo) => {
  console.log(`Slot: ${slotInfo.slot}`);
});

// Log subscription
connection.onLogs(
  new PublicKey("PROGRAM_ID"),
  (logs, ctx) => {
    console.log(`Tx: ${logs.signature}`);
    logs.logs.forEach(log => console.log(" ", log));
  },
  "confirmed"
);

Python——监控账户

import asyncio, json, os
import websockets

WALLET = "YOUR_WALLET_ADDRESS"

async def watch_account():
    uri = f"wss://wss-rpc.carbium.io/?apiKey={os.environ['CARBIUM_RPC_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1,
            "method": "accountSubscribe",
            "params": [WALLET, {"encoding": "base64", "commitment": "confirmed"}],
        }))
        ack = json.loads(await ws.recv())
        print(f"Subscribed: {ack['result']}")
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("method") == "accountNotification":
                val = msg["params"]["result"]["value"]
                print(f"Balance: {val['lamports'] / 1e9} SOL")

asyncio.run(watch_account())

取消订阅

每种订阅方法都有对应的取消订阅方法。使用确认消息中的订阅 ID：

{"jsonrpc": "2.0", "id": 2, "method": "accountUnsubscribe", "params": [SUBSCRIPTION_ID]}

订阅	取消订阅
slotSubscribe	slotUnsubscribe
accountSubscribe	accountUnsubscribe
programSubscribe	programUnsubscribe
signatureSubscribe	signatureUnsubscribe（首次通知后自动取消）
logsSubscribe	logsUnsubscribe
blockSubscribe	blockUnsubscribe
rootSubscribe	rootUnsubscribe

如需查看完整通知格式和高级用法，请参阅 resources/websocket-reference.md。

---

gRPC / 完整区块串流

兼容 Yellowstone 的实时完整区块串流。延迟约为 22ms。提供完整原子区块，无需重新组装 shred。

端点与身份验证

方法	格式	用例
WebSocket 查询参数	wss://grpc.carbium.io/?apiKey=YOUR_RPC_KEY	推荐用于 TS/Python
HTTP/2 标头	x-token: YOUR_RPC_KEY	用于 Rust yellowstone-grpc-client

需要 Business 套餐或更高套餐。

可用方法

方法	描述
transactionSubscribe	使用筛选器订阅实时交易
transactionUnsubscribe	取消订阅交易串流

TypeScript——订阅程序交易

import WebSocket from "ws";

const PROGRAM_ID = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";

const ws = new WebSocket(
  `wss://grpc.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "transactionSubscribe",
    params: [
      {
        vote: false,
        failed: false,
        accountInclude: [PROGRAM_ID],
        accountExclude: [],
        accountRequired: [],
      },
      {
        commitment: "confirmed",
        encoding: "base64",
        transactionDetails: "full",
        showRewards: false,
        maxSupportedTransactionVersion: 0,
      },
    ],
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.result !== undefined) {
    console.log(`Subscribed, ID: ${msg.result}`);
    return;
  }
  if (msg.method === "transactionNotification") {
    const { signature, slot } = msg.params.result;
    console.log(`tx ${signature} in slot ${slot}`);
  }
});

// Always reconnect on close — see Production Patterns
ws.on("close", (code) => {
  console.warn(`Disconnected (${code}), reconnecting...`);
});

筛选字段

字段	类型	描述
vote	bool	包含投票交易
failed	bool	包含失败的交易
accountInclude	string[]	包含涉及这些账户中任意一个的交易
accountExclude	string[]	排除涉及这些账户的交易
accountRequired	string[]	仅包含涉及所有这些账户的交易

accountInclude 或 accountRequired 中至少有一个必须包含值。

订阅选项

字段	类型	值
commitment	string	processed / confirmed / finalized
encoding	string	base64 / base58 / jsonParsed
transactionDetails	string	full / signatures / none
showRewards	bool	包含奖励信息
maxSupportedTransactionVersion	number	0 表示 legacy + v0

Python

import asyncio, json, os
import websockets

PROGRAM_ID = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"

async def subscribe():
    uri = f"wss://grpc.carbium.io/?apiKey={os.environ['CARBIUM_RPC_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "jsonrpc": "2.0", "id": 1,
            "method": "transactionSubscribe",
            "params": [
                {
                    "vote": False, "failed": False,
                    "accountInclude": [PROGRAM_ID],
                    "accountExclude": [], "accountRequired": [],
                },
                {
                    "commitment": "confirmed", "encoding": "base64",
                    "transactionDetails": "full", "showRewards": False,
                    "maxSupportedTransactionVersion": 0,
                },
            ],
        }))
        async for message in ws:
            data = json.loads(message)
            if "result" in data:
                print(f"Subscribed: {data['result']}")
            elif data.get("method") == "transactionNotification":
                print(f"tx: {data['params']['result']['signature'][:20]}...")

asyncio.run(subscribe())

Rust（HTTP/2 gRPC）

use yellowstone_grpc_client::GeyserGrpcClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = GeyserGrpcClient::connect(
        "https://grpc.carbium.io",
        "YOUR_RPC_KEY",  // passed as x-token header automatically
        None,
    )?;
    let (_subscribe_tx, mut stream) = client.subscribe().await?;
    // Define subscription filters and consume stream
    Ok(())
}

完整区块与 Shreds

指标	值	说明
Solana Slot 解析时间	~400ms	生成一个区块的时间窗口
竞品「Shreds」	~9ms	需要客户端重新组装的分片数据
Carbium 完整区块	~22ms	原子、完整，可直接使用的数据

在 400ms 的 Slot 内，13ms 的差异微不足道。完整区块提供原子完整性、无需逻辑处理的数据摄取，以及高效解析。

取消订阅

{"jsonrpc": "2.0", "id": 2, "method": "transactionUnsubscribe", "params": [SUBSCRIPTION_ID]}

有关响应结构的完整 gRPC 参考，请参阅 resources/grpc-reference.md。

---

Swap API

由 CQ1 引擎驱动的聚合 DEX 报价和执行功能——亚毫秒级报价、约 10ms 的链上到可查询延迟，以及原生二进制状态。

基础 URL： https://api.carbium.io 身份验证： 所有请求均需在请求头中添加 X-API-KEY: YOUR_API_KEY 获取密钥： api.carbium.io/login（免费账户）

API 版本

版本	接口	状态
v2（Q1）	GET /api/v2/quote	当前版本——新集成请使用此版本
v1（旧版）	GET /api/v1/quote、/api/v1/swap、/api/v1/quote/all、/api/v1/swap/bundle	旧版——仍可使用

重要： v2 和 v1 使用不同的参数名称。请勿混用。v2（Q1）使用 src_mint/dst_mint/amount_in/slippage_bps。v1 使用 fromMint/toMint/amount/slippage。

v2 / Q1 — 报价 + 可执行交易（推荐）

如果包含 user_account，Q1 引擎会在一次调用中同时返回报价和可执行交易。无需单独的 Swap 端点。

GET /api/v2/quote

参数	必填	说明
src_mint	是	输入代币的 Mint 地址
dst_mint	是	输出代币的 Mint 地址
amount_in	是	以最小单位（lamports）表示的输入金额
slippage_bps	是	以基点表示的滑点容差
user_account	否	钱包地址——如果包含，响应会包含可执行的 txn 字段

仅报价（不含交易）：

const quote = await fetch(
  "https://api.carbium.io/api/v2/quote" +
  "?src_mint=So11111111111111111111111111111111111111112" +
  "&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" +
  "&amount_in=1000000000" +
  "&slippage_bps=100",
  { headers: { "X-API-KEY": process.env.CARBIUM_API_KEY! } }
).then(r => r.json());
// Returns: { srcAmountIn, destAmountOut, destAmountOutMin, priceImpactPct, routePlan }

报价 + 可执行交易（包含 user_account）：

const quote = await fetch(
  "https://api.carbium.io/api/v2/quote" +
  "?src_mint=So11111111111111111111111111111111111111112" +
  "&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" +
  "&amount_in=1000000000" +
  "&slippage_bps=100" +
  "&user_account=YOUR_WALLET_ADDRESS",
  { headers: { "X-API-KEY": process.env.CARBIUM_API_KEY! } }
).then(r => r.json());
// Returns: { srcAmountIn, destAmountOut, destAmountOutMin, priceImpactPct, routePlan, txn }
// txn is base64-encoded, ready for deserialization and signing

import httpx, os

resp = httpx.get(
    "https://api.carbium.io/api/v2/quote",
    params={
        "src_mint": "So11111111111111111111111111111111111111112",
        "dst_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "amount_in": 1_000_000_000,
        "slippage_bps": 100,
        "user_account": "YOUR_WALLET_ADDRESS",  # include for executable txn
    },
    headers={"X-API-KEY": os.environ["CARBIUM_API_KEY"]},
)
print(resp.json())

v1 旧版端点

这些端点仍可使用，但采用较旧的参数系列。请勿将 v1 参数与 v2 URL 混用。

端点	方法	参数	说明
/api/v1/quote	GET	fromMint、toMint、amount、slippage、provider	特定提供方的报价
/api/v1/quote/all	GET	fromMint、toMint、amount、slippage	比较所有提供方的报价
/api/v1/swap	GET	owner、fromMint、toMint、amount、slippage、provider + 可选标志	获取序列化的 Swap 交易
/api/v1/swap/bundle	GET	signedTransaction	通过 Jito bundle 提交（MEV 保护）
/api/v1/fee/custom	GET	payer、receiver、lamports	生成自定义费用转账交易

v1 /swap 支持其他执行标志：gasless、mevSafe、priorityMicroLamports、feeLamports、feeReceiver、pool。

完整 Swap 执行流程（TypeScript）——v2/Q1

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

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

// 1. Get quote with executable transaction (single call)
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", "100000000");
url.searchParams.set("slippage_bps", "100");
url.searchParams.set("user_account", "YOUR_WALLET_ADDRESS");

const quote = await fetch(url, {
  headers: { "X-API-KEY": process.env.CARBIUM_API_KEY! },
}).then(r => r.json());

if (!quote.txn) throw new Error("No executable transaction — check user_account param");

// 2. Deserialize and sign
const tx = VersionedTransaction.deserialize(Buffer.from(quote.txn, "base64"));
// tx.sign([yourKeypair]);

// 3. Submit via RPC
const sig = await connection.sendRawTransaction(tx.serialize(), { maxRetries: 3 });

// 4. Confirm
await connection.confirmTransaction(sig, "confirmed");
console.log("Swap confirmed:", sig);

支持的 DEX 提供方

提供方	ID
Raydium	raydium
Raydium CPMM	raydium-cpmm
Orca	orca
Meteora	meteora
Meteora DLMM	meteora-dlmm
Pump.fun	pump-fun
Moonshot	moonshot
Stabble	stabble
PrintDEX	printdex
GooseFX	goosefx

滑点建议

交易对类型	建议 BPS	百分比
稳定币兑换	5-10	0.05-0.1%
主流交易对（SOL/USDC）	10-50	0.1-0.5%
波动性代币	50-100	0.5-1%
套利	10	0.1%（严格）

完整的 OpenAPI 参数规范，请参阅 resources/swap-api-reference.md。

---

无 Gas 兑换

无 Gas 兑换允许用户在不持有 SOL 来支付费用的情况下执行链上交易。

工作原理

1. 用户发起兑换
2. Carbium 从内部费用池中垫付 SOL 费用
3. 交易正常在链上结算
4. 通过对兑换输出进行微调来重新平衡费用池

限制

无 Gas 兑换要求输出代币为 SOL。目前可通过 v1 兑换端点使用。

适用场景

• 收到代币但没有 SOL 的新用户
• 追求低门槛注册体验的嵌入式钱包
• 先兑换的 UX，避免 Gas 资金需求影响转化率

集成

在 v1 兑换请求中添加 gasless=true：

const res = await fetch(
  "https://api.carbium.io/api/v1/swap" +
  "?owner=WALLET&fromMint=USDC_MINT&toMint=SOL_MINT" +
  "&amount=1000000&slippage=100&provider=raydium&gasless=true",
  { headers: { "X-API-KEY": process.env.CARBIUM_API_KEY! } }
);

---

Pump.fun 毕业前代币狙击

Carbium Swap API 无法路由毕业前的 pump.fun 代币（返回 0 条路由）。请使用：通过 gRPC 检测新代币发行 → 构建原始 bonding curve 交易 → 通过 RPC 提交。

需要 Business tier RPC 密钥（gRPC 访问权限）。

关键常量

const PUMP_PROGRAM       = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const PUMP_GLOBAL        = "4wTV1YmiEkRvAtNtsSGPtUrqRYQMe5SKy2uB4Jjaxnjf";
const PUMP_FEE_RECIPIENT = "CebN5WGQ4jvEPvsVU4EoHEpgzq1VV7AbicfhtW4xC9iM";
const PUMP_EVENT_AUTH    = "Ce6TQqeHC9p8KetsN6JsjHK7UTZk7nasjjnr7XxXp9F1";
const GRADUATION_SOL     = 85_000_000_000n; // 85 SOL in lamports
const TOTAL_SUPPLY       = 1_000_000_000_000_000n; // 1 quadrillion (6 decimals)

const DISCRIMINATORS = {
  create: [0xe4, 0x45, 0xa5, 0x2e, 0x51, 0xcb, 0x9a, 0x1d],
  buy:    [0x66, 0x06, 0x3d, 0x12, 0x01, 0xda, 0xeb, 0xea],
  sell:   [0x33, 0xe6, 0x85, 0xa4, 0x01, 0x7f, 0x83, 0xad],
};

步骤 1 — 通过 gRPC 订阅新代币发行

import WebSocket from "ws";

const ws = new WebSocket(
  `wss://grpc.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0", id: 1,
    method: "transactionSubscribe",
    params: [
      { vote: false, failed: false, accountInclude: [PUMP_PROGRAM] },
      { commitment: "confirmed", encoding: "jsonParsed",
        transactionDetails: "full", showRewards: false,
        maxSupportedTransactionVersion: 0 },
    ],
  }));
});

setInterval(() => ws.ping(), 30_000); // keepalive

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.method !== "transactionNotification") return;
  const { signature, transaction } = msg.params.result;
  const logs = transaction.meta.logMessages || [];
  for (const log of logs) {
    if (log.includes("Instruction: Create")) {
      const mint = transaction.meta.postTokenBalances[0]?.mint;
      if (mint) handleNewToken(mint, signature);
    }
  }
});

步骤 2 — 派生 Bonding Curve PDA

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

function deriveBondingCurve(mint: string): PublicKey {
  const [address] = PublicKey.findProgramAddressSync(
    [Buffer.from("bonding-curve"), new PublicKey(mint).toBuffer()],
    new PublicKey(PUMP_PROGRAM)
  );
  return address;
}

步骤 3 — 获取并解析 Bonding Curve 状态

// Bonding curve layout (81 bytes):
// [0-7]   discriminator
// [8-15]  virtualTokenReserves (u64 LE)
// [16-23] virtualSolReserves   (u64 LE)
// [24-31] realTokenReserves    (u64 LE)
// [32-39] realSolReserves      (u64 LE)
// [40-47] tokenTotalSupply     (u64 LE)
// [72]    complete             (bool)

async function fetchBondingCurve(address: PublicKey) {
  const res = await fetch(`https://rpc.carbium.io/?apiKey=${process.env.CARBIUM_RPC_KEY}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1,
      method: "getAccountInfo",
      params: [address.toBase58(), { encoding: "base64" }],
    }),
  });
  const { result } = await res.json();
  const data = Buffer.from(result.value.data[0], "base64");
  return {
    virtualTokenReserves: data.readBigUInt64LE(8),
    virtualSolReserves:   data.readBigUInt64LE(16),
    realTokenReserves:    data.readBigUInt64LE(24),
    realSolReserves:      data.readBigUInt64LE(32),
    complete:             data.readUInt8(72) === 1,
  };
}

步骤 4 — 报价（恒定乘积 AMM）

function quoteBuy(curve: any, solLamports: number): bigint {
  const num = curve.virtualTokenReserves * BigInt(solLamports);
  const den = curve.virtualSolReserves + BigInt(solLamports);
  return num / den;
}

function quoteSell(curve: any, tokens: bigint): bigint {
  const num = curve.virtualSolReserves * tokens;
  const den = curve.virtualTokenReserves + tokens;
  return num / den;
}

步骤 5 — 构建并提交买入交易

买入指令账户（顺序重要，共 13 个）：

#	账户	访问权限
0	PUMP_GLOBAL	读取
1	PUMP_FEE_RECIPIENT	写入
2	mint	读取
3	bondingCurve	写入
4	bondingCurve ATA	写入
5	user ATA	写入
6	user/payer	写入，签名者
7	SystemProgram	-
8	TokenProgram	-
9	AssociatedTokenProgram	-
10	Rent sysvar	-
11	PUMP_EVENT_AUTH	读取
12	PUMP_PROGRAM	读取

使用 skipPreflight: true 提交，可节省约 200ms：

const sig = await connection.sendRawTransaction(signedTx.serialize(), {
  skipPreflight: true,
  preflightCommitment: "confirmed",
  maxRetries: 3,
});

狙击流程概要

gRPC "Create" event → extract mint
  → deriveBondingCurve(mint)
  → [optional] fetchBondingCurve() for price check
  → build buy instruction with desired SOL
  → sendTransaction(skipPreflight: true)
  → monitor bonding curve state for exit
  → sell when target % reached or graduation imminent (85 SOL)

Pump.fun 错误处理

错误	原因	解决方法
区块哈希已过期	Tx 耗时过长	使用更新的区块哈希；降低延迟
资金不足	SOL 不足	余额必须覆盖金额和费用（约 0.005 SOL）
找不到账户	代币刚创建	稍作延迟后重试（50-100ms）
超出滑点	价格已变动	增大 maxSolCost 或减小规模

完整的狙击示例，请参阅 examples/pump-snipe/example.ts。

---

迁移

从其他 RPC 服务商迁移（Helius、QuickNode、Triton、Alchemy）

只需简单替换 URL — 它们都使用标准 JSON-RPC：

// Before
const connection = new Connection("https://mainnet.helius-rpc.com/?api-key=...");

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

从 Jupiter Swap API 迁移

参数映射（v2/Q1）：

Jupiter	Carbium v2/Q1 (/api/v2/quote)
inputMint	src_mint
outputMint	dst_mint
amount	amount_in
slippageBps	slippage_bps

主要区别：当包含 user_account 时，Carbium Q1 会在报价响应中返回可执行交易。无需单独调用兑换接口。

从 Triton gRPC 迁移

使用相同的 Yellowstone 协议。只需更新端点：

wss://grpc.carbium.io/?apiKey=YOUR_RPC_KEY

详细迁移指南，请参阅 docs/migration.md。

---

生产环境模式

指数退避重试

const delay = (ms: number) => new Promise(r => setTimeout(r, ms));

async function withRetry<T>(fn: () => Promise<T>, retries = 3, baseMs = 300): Promise<T> {
  for (let i = 0; i < retries; i++) {
    try { return await fn(); }
    catch (e) {
      if (i === retries - 1) throw e;
      await delay(baseMs * 2 ** i + Math.random() * 100);
    }
  }
  throw new Error("unreachable");
}

切勿盲目重试 sendTransaction — 请先检查 getSignatureStatus，确认交易尚未上链。

WebSocket / gRPC 重连

async function connectWithReconnect(connectFn: () => Promise<void>) {
  let backoff = 1000;
  while (true) {
    try {
      await connectFn();
      backoff = 1000; // reset on success
    } catch {
      await delay(backoff);
      backoff = Math.min(backoff * 2, 30_000); // cap at 30s
    }
  }
}

每 30 秒发送一次 ping，以防止连接静默断开。

超时建议

操作	超时时间
RPC 读取调用	5-10s
兑换报价	3-5s
交易确认	30-60s（使用轮询）

故障处理

故障	操作
报价：未找到路由	提高滑点或更换提供方后重试
模拟失败	不要发送——检查错误、记录日志并发出告警
sendTransaction 失败	重试前检查 getSignatureStatus
交易未确认	轮询并设置超时；检查区块哈希是否过期
流连接断开	使用指数退避重新连接
HTTP 429 速率限制	立即退避；将其视为架构信号

---

错误参考

HTTP 状态码

代码	含义	操作
401	API 密钥无效或缺失	检查密钥和身份验证格式
403	套餐限制（例如，免费套餐不支持 gRPC）	在 rpc.carbium.io 升级
429	超出速率限制	退避并重试；检查架构
400	未找到路由／参数错误	检查 Mint 地址、滑点和必填参数
500	服务器错误	1s 后重试
503	暂时不可用	使用指数退避重试

WebSocket 错误代码

代码	消息	原因
-32700	解析错误	JSON 格式错误或缺少必填参数
-32601	找不到方法	方法名称拼写错误或不支持该方法
-32602	参数无效	参数类型错误或缺少字段
-32603	内部错误	服务器端错误——重试

---

常见代币 Mint 地址

代币	Mint 地址
SOL（封装版）	So11111111111111111111111111111111111111112
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

---

最佳实践

安全

• 仅在服务器端保存 API 密钥——切勿放入前端包或移动客户端
• 使用环境变量（CARBIUM_RPC_KEY、CARBIUM_API_KEY）
• 如果密钥泄露，立即轮换
• 在实际可行时，于 RPC 控制面板中按域名／IP 限制端点

速率限制

• HTTP 429 是架构信号，而不只是重试提示
• 分开使用开发、预发布和生产密钥
• 将重试路径与决策逻辑隔离
• 检查 getSignatureStatus 之前，切勿重试 sendTransaction

交易提交

• 仅在验证报价后使用 skipPreflight: true——可节省约 200ms
• 使用 VersionedTransaction（V0）以支持地址查找表（ALT）
• 确认时优先使用 HTTP 轮询，而非 WebSocket（更可靠）
• 保持区块哈希为最新状态——它们会在约 60s 后过期

Commitment 级别

• 大多数操作默认使用 confirmed
• 仅在价格 Feed 或低风险读取操作中使用 processed
• 对不可逆确认和高价值操作使用 finalized

---

技能结构

skills/carbium/
├── SKILL.md                              # This file
├── resources/
│   ├── endpoints-and-auth.md             # All endpoints, auth patterns, pricing
│   ├── swap-api-reference.md             # Full Swap API parameter specs
│   ├── grpc-reference.md                 # gRPC filter fields, response shapes
│   └── websocket-reference.md            # All WSS subscription methods and shapes
├── examples/
│   ├── rpc-basic/README.md               # Balance check + send transaction
│   ├── swap-quote/README.md              # Quote → swap → sign → submit
│   ├── swap-bundle/README.md             # MEV-protected Jito bundle
│   ├── grpc-stream/README.md             # Program transaction subscription
│   ├── websocket-monitor/README.md       # Account + slot monitoring via WSS
│   ├── pump-snipe/README.md              # Full pump.fun sniping flow
│   └── gasless-swap/README.md            # Gasless swap execution
├── templates/
│   └── carbium-setup.ts                  # Connection setup + retry helper
└── docs/
    ├── troubleshooting.md                # Error codes, 429 handling
    ├── migration.md                      # From Helius, QuickNode, Jupiter
    └── trading-bots.md                   # Bot architecture patterns

---

参考资料

资源	URL
生态系统概览	docs.carbium.io/docs/the-carbium-ecosystem
RPC 快速入门	docs.carbium.io/docs/quick-start-rpc
Swap API 快速入门	docs.carbium.io/docs/quick-start-dex-api
gRPC／流式传输	docs.carbium.io/docs/solana-grpc
CQ1 引擎	docs.carbium.io/docs/cq1-engine-overview
RPC 定价	docs.carbium.io/docs/carbium-rpc-pricing
API 示例	docs.carbium.io/recipes
常见问题	docs.carbium.io/docs/faq
完整 AI 上下文	carbium.io/llms-ctx.txt
RPC 注册	rpc.carbium.io/signup
Swap API 注册	api.carbium.io/login
Discord	discord.gg/jW7BUkQS5U
Twitter/X	x.com/carbium