treasures

Treasures Finance Agent Skills

用于基于 Treasures 金融 API 构建 AI Agent 的 Agent Skills。

技能是一个包含纯 Markdown 指令（SKILL.md）的文件夹，编码 Agent 会按需加载这些指令。这里的技能教会 Agent 如何正确调用 Treasures 金融 API——发现代币化股票、报价并执行交易、跨链桥接 USDC、操作委托钱包，以及读取投资组合——并涵盖容易出错的签名细节和注意事项。

技能目录

技能	功能
treasures-b2b-api（上游：treasures-io/treasures-finance-agent-skills）	基于 Treasures 公共 B2B API 构建 Agent：发现代币化股票、报价并执行交易、在 Solana 和 Ethereum 之间桥接 USDC，以及读取单个终端用户钱包对的投资组合和交易历史。涵盖端点选择、所有权证明签名（包括嵌入式钱包）、交易／桥接执行和错误处理。
treasures-wallet（上游：treasures-io/treasures-finance-agent-skills）	通过 HTTP 操作 Treasures 委托钱包：引导用户（配置钱包并生成限定范围的 API 密钥）、报价、执行异步买卖（非托管——Agent 从不签名；Treasures 作为委托签名者签名，权限严格限定于 RWA 交易）、读取余额／投资组合／交易历史，以及管理 API 密钥。通过 HTTPS 和 API 密钥即可在 Solana 或 Ethereum 上交易代币化股票（xStocks／Ondo）与 USDC——无需 web3 库、密钥或 RPC。

⚠️ 尝试任何交易前请阅读（已于 2026-07-27 实时验证）

如果不了解以下两点，都会导致请求静默失败。两者均通过实时调用确认，并非来自文档。

1. 基础 URL 需要路径前缀

单独使用 https://api.treasures.io 时，所有路径都会返回 404。同一主机上有两个平面：

平面	基础 URL	用途
公共 B2B	https://api.treasures.io/public/v1	treasures-b2b-api（默认）
委托 Agent	https://api.treasures.io/api/v1	treasures-wallet

2. 负载均衡器会对交易路径进行地理围栏限制

读取请求在全球范围内开放；写入请求则不开放。

路径	来自受限 IP 的结果
GET /stocks/*、/portfolio、/trades	✅ 200
POST /quote/buy、/quote/sell、/bridge/quote、/trade/submit	❌ 451 unavailable_for_legal_reasons

• 限制位于 AWS 负载均衡器（server: awselb/2.0），匹配依据是路径 + 实际 TCP 来源 IP，发生在身份验证之前，也发生在应用之前。未知路径返回 404（而不是 451），交易路径上的 GET／OPTIONS 请求也会返回 451 → 受限的是路径，而不是写入方法。两个平面都受此限制——/api/v1/quote/sell 和 /public/v1/quote/sell 一样会返回 451。
• 伪造地理位置请求头不起作用（X-Forwarded-For、CF-IPCountry、X-Real-IP、True-Client-IP 仍然都会返回 451）。
• 受限地区： 美国（Starchild 的默认出口位于加利福尼亚州圣何塞）和英国。不受限地区： 德国、荷兰、瑞典、瑞士、新加坡、香港、日本——已通过 sc-vpn 技能使用逐请求代理（proxies=／curl -x）进行测试。切勿设置全局 HTTP_PROXY；这会破坏 sc-proxy 计费。

451 绝不是钱包、签名或委托问题。 在通过地理位置限制之前，不要排查签名问题。

/quote/sell 上的错误阶梯——告诉你请求被哪一层拒绝

451 unavailable_for_legal_reasons  → geo edge (change exit region)
400 invalid_request                → schema (fix the body)
401 ownership_proof_eth_invalid    → signature (re-sign the challenge)
422 holdings_insufficient          → auth OK, wallet just lacks the asset

请求到达 422，证明地理位置检查和签名都正常——这是最理想的失败情况。

资格要求——不可忽视

451 是按设计执行的资格规则，并非服务中断。Ondo／xStocks 代币化股票不向美国人士提供；此外，Ondo 还会在代币合约层执行 KYC／转让白名单检查，因此无资格的钱包无论出口 IP 显示什么，都会在链上遭到拒绝。在绕过地理围栏之前，请确认用户符合获准司法管辖区的资格要求。 为真正非美国用户解除地理位置限制没有问题；但不得利用此举规避证券限制。

如何通过 sc-vpn 路由交易调用

前提条件：sc-vpn skill（官方）。如果尚未安装，请运行 npx skills add Starchild-ai-agent/official-skills --skill sc-vpn --agent openclaw。无需凭据；仅限内部网络。健康检查：curl http://sc-vpn.internal:8081/health → {"status": "ok"}。

代理 URL 格式为 http://<region>:[email protected]:8080——用户名是地区代码。如果省略，则会收到 400 No region specified。

规则：读取请求直接访问，只有围栏标出的交易路径才通过 VPN。 所有请求都走隧道既慢又没必要——/stocks、/portfolio 和 /trades 从任何地方都能访问。

import requests, time
from core.skill_tools import wallet   # run from a dir where `core` is importable (e.g. /tmp or /data/workspace)

BASE = "https://api.treasures.io/public/v1"
VPN  = "http://de:[email protected]:8080"          # de | nl | se | ch | sg | hk | jp
PROX = {"http": VPN, "https": VPN}                  # per-request ONLY — never os.environ

ETH = "0x...".lower()                               # wallet address, lowercase

# READ — direct, no proxy
pf = requests.get(f"{BASE}/portfolio", params={"eth_wallet": ETH}, timeout=30).json()

# WRITE — through the VPN, with a signed ownership proof
issued    = int(time.time())
challenge = f"treasures-finance-quote-v1\n{issued}\n\n{ETH}"     # verified format; note the blank line
sig       = wallet.wallet_sign(challenge)["signature"]

body = {
    "ticker": "GOOGL", "chain": "eth",
    "amount_shares": "0.01", "max_slippage_bps": 100,
    "eth_wallet": ETH,
    "ownership_proof": {"issued_at": issued, "eth_signature": sig},
}
r = requests.post(f"{BASE}/quote/sell", json=body, proxies=PROX, timeout=60)
print(r.status_code, r.text)      # 422 holdings_insufficient = geo + signing both OK

在 bash 中执行效果相同：

curl -x "http://de:[email protected]:8080" \
     -X POST https://api.treasures.io/public/v1/quote/sell \
     -H 'content-type: application/json' -d @body.json

在信任结果前，确认出口 IP：curl -x "http://de:[email protected]:8080" https://ipinfo.io/json。

容易踩的坑

症状	原因
通过 VPN 仍然返回 451	该地区本身也被封锁了——GB 也在限制范围内。请使用 DE/NL/SE/CH/SG/HK/JP。
其他 API 开始全部返回 401	你设置了全局 HTTP_PROXY，绕过了 sc-proxy。取消设置；对每个请求使用 proxies=。
400 Bad Request: No region specified	代理 URL 中缺少地区用户名。
502 Unknown region	地区代码不在 sc-vpn 的 18 个地区列表中。
401 ownership_proof_eth_invalid	这是证明问题，不是地理位置问题——检查地址是否为小写、issued_at 是否为最新值，以及挑战字符串是否完全一致。

整个交易流程（/quote/* → /trade/submit，以及 /bridge/quote → bridge submit）都要使用同一出口地区。流程中途切换出口可能导致后端看到交易各阶段的来源不一致。

安装

# Install one sub-skill (recommended — pulls just what you need)
npx skills add treasures-io/treasures-finance-agent-skills --skill treasures-b2b-api
npx skills add treasures-io/treasures-finance-agent-skills --skill treasures-wallet

# Or install everything (auto-detects your environment and installs accordingly)
npx skills add treasures-io/treasures-finance-agent-skills

npx skills 会将 SKILL.md 文件安装到适用于 70 多种编码 Agent 的正确位置（Claude Code、Codex、Cursor、GitHub Copilot、Windsurf、Cline、OpenCode，……），并自动检测你已安装的 Agent。它会直接读取此仓库的 skills/<name>/SKILL.md 布局，因此无需额外设置。

使用 -a 指定目标 Agent：

npx skills add treasures-io/treasures-finance-agent-skills -a claude-code -a codex -a cursor

许可证

MIT