Solana 支付 (x402)

使用 Solana 主网上的 USDC 支付 API 调用费用。SDK 使用与 Base 链相同的 x402 协议 — 仅密钥格式不同。

安装

# 标准版（仅支持 EVM / Base 链）
pip install jarvisclaw

# 支持 Solana
pip install jarvisclaw[solana]

自动链检测

SDK 如何选择链

• 0x... — EVM 十六进制密钥 → Base 链 (Chain ID 8453)，USDC ERC-20
• bs58 — Solana 密钥对 → Solana 主网，USDC SPL

无需配置标志 — 传入密钥，SDK 自动处理。

Solana 要求

• 持有 USDC (SPL) 的 Solana 主网钱包
• 从 Phantom 或 Solflare 导出完整密钥对（不仅仅是公钥）
• 导出的密钥为 base58 编码字符串

初始化

将 Solana 密钥对字符串作为 private_key 传入 — SDK 自动检测 Solana。

Python

from jarvisclaw import ChatClient, ImageClient

# EVM 钱包 — 十六进制私钥 (0x...) → Base 链 (Chain ID 8453)
chat = ChatClient(private_key="0x<evm-wallet-private-key>")

# Solana 钱包 — bs58 编码密钥对 → Solana 主网
# SDK 自动检测：如果密钥是 base58 且非十六进制，则使用 Solana
chat = ChatClient(private_key="<base58-solana-keypair>")

# 显式网络选择
chat = ChatClient(private_key="<key>", network="solana")

Go

// ⚠️ 即将推出 — Go SDK 暂不支持 Solana。以下为 API 预览。
// Go 当前仅支持 Base 链 (EVM)。

import jarvisclaw "github.com/api-jarvisclaw/go-sdk/v2"

// EVM 钱包 — 十六进制私钥 (0x...) → Base 链
client, _ := jarvisclaw.NewChatClient(jarvisclaw.WithPrivateKey("0x<evm-private-key>"))

// Solana 钱包 — bs58 编码密钥对 → Solana 主网（即将推出）
// SDK 从密钥格式自动检测链
client, _ := jarvisclaw.NewChatClient(jarvisclaw.WithPrivateKey("<base58-solana-keypair>"))

完整示例

所有客户端类型都支持 Solana — 对话、图像、视频、音频。仅支付层不同。

Python

# pip install jarvisclaw[solana]
from jarvisclaw import ChatClient, ImageClient, VideoClient

# 传入 Solana bs58 密钥对 — SDK 自动检测 Solana
chat = ChatClient(private_key="<base58-solana-keypair>")
image = ImageClient(private_key="<base58-solana-keypair>")

# 所有端点完全相同 — 仅支付链不同
response = chat.complete("你好，来自 Solana！")
print(response)

# 查看余额
print(f"余额: ${chat.get_balance():.2f} USDC (Solana)")

# 图像生成 —— generate() 返回对象，URL 在 .url 上
img = image.generate("赛博朋克东京")
print(img.url)

# 钱包地址（Solana 模式下为 Solana 公钥）
print(chat.address)

多链 Fallback

使用 API Key 时，平台支持多链自动 fallback：

1. 首先尝试 Base 链 USDC 余额
2. 如果 Base 余额不足，自动切换到 Solana USDC
3. 两个链都不足时返回 402 错误

# API Key 模式 — 自动多链 fallback，无需关心链选择
chat = ChatClient(api_key="sk-your-api-key")
response = chat.complete("平台自动选择最优链结算")

与 Base 链对比

特性	Base (EVM)	Solana
Token	USDC (ERC-20)	USDC (SPL)
确认时间	~2 秒	~400 毫秒
Gas 费	极低 (~$0.001)	极低 (~$0.0001)
SDK 支持	Python + Go	仅 Python
密钥格式	十六进制 (0x...)	Base58

ATA（关联代币账户）要求

Solana 上的 SPL 代币需要一个关联代币账户才能收发。尝试 Solana 结算前，平台会先做 ATA 预检：

检查项	验证内容
发送方 ATA	付款钱包已初始化 USDC SPL 代币账户
余额	该 ATA 持有足额 USDC

若 ATA 不存在或余额为零，Solana 路径会被立即跳过（不做失败的交易模拟），转而回退到 Base 或返回错误。

常见问题

从未持有过 USDC 的新 Solana 钱包在链上没有初始化 ATA。你必须先收到至少一笔 USDC 转账 （哪怕 0.000001）来创建 ATA，之后 x402 才能在 Solana 上完成结算。

如何确认 ATA 已就绪

1. 向你的 Solana 钱包地址发送任意数量的 USDC（SPL）—— 这会自动创建 ATA。
2. 或用 Solana 钱包应用（Phantom、Solflare）添加 USDC 代币 —— 部分钱包会主动创建 ATA。
3. 调用 /v1/wallet/balance，若 wallets.solana.usdc 有返回值（即使是 0.000000）， 说明 ATA 已存在。

402 中的 Solana 选项

只有在 Solana 已配置且网关已从 facilitator 解析出 fee payer 时，402 响应的 accepts 才会 包含 Solana 选项 —— 缺少 fee payer 无法构造并签名 SVM 交易。在此之前只会列出 Base。

Solana 选项的 extra 字段装的是 feePayer（EVM 选项装的是 EIP-712 domain）。详见 Agent 支付 (x402)。