交易市场 API

传统市场实时价格数据。覆盖 12 个全球交易所的 1,746 只股票，预言机刷新频率约 400ms。另有 500+ 加密货币对、30+ 外汇对和大宗商品。所有端点统一 $0.001/次。

基础 URL： https://api.jarvisclaw.ai/v1/marketplace/markets

认证

两种方式均支持：

方式	Header	描述
API Key	`Authorization: Bearer sk-...`	平台自动从你的 HD 钱包签名 x402
私钥 (x402)	SDK 自动处理	Agent 直接用自己的钱包签名 x402

定价

范围	价格
所有端点，所有资产类别	$0.001/次

加密、外汇、大宗商品并非免费

本服务统一按 $0.001/次计价，没有按资产类别的例外。旧文档把加密/外汇/大宗商品读取描述为免费，那已经过时。精确扣费金额请读响应中的 price.amount。

端点

方法	端点	描述	价格
GET	/stocks/:market/price/:symbol	单只股票实时价格（如 `/stocks/us/price/AAPL`）	$0.001
GET	/crypto/price/:pair	加密货币对价格（如 `BTC-USD`）	$0.001
GET	/fx/price/:pair	外汇对价格（如 `EUR-USD`）	$0.001
GET	/commodity/price/:symbol	大宗商品价格（如 `XAU-USD`）	$0.001

路径是单数

是 /fx/ 和 /commodity/，不是 /forex/ 或 /commodities/。也没有 /list 或 /batch 端点 —— 只能逐个符号查询。

支持的交易所

代码	地区	代表标的
`us`	美国	AAPL、NVDA、TSLA、MSFT、GOOGL、AMZN
`gb`	英国	SHEL、AZN、HSBA、ULVR
`de`	德国	SAP、SIE、ALV、BAS
`fr`	法国	MC、OR、SAN、AIR
`nl`	荷兰	ASML、INGA、PHIA
`ie`	爱尔兰	CRH、KYGA、SKG
`lu`	卢森堡	ARCE、SES、RTL
`hk`	香港	0700、9988、0005、1299
`jp`	日本	7203、6758、9984、6861
`kr`	韩国	005930、000660、035420
`cn`	中国	600519、601318、000858
`ca`	加拿大	RY、TD、SHOP、ENB

GET /stocks/:market/price/:symbol

获取单只股票的实时价格。

参数

参数	类型	必填	描述
`market`	string (路径)	是	市场代码：`us`、`hk`、`jp` 等
`symbol`	string (路径)	是	股票代码：`AAPL`、`0700`、`7203`

响应

json

{
  "symbol": "AAPL",
  "exchange": "us",
  "price": 245.82,
  "currency": "USD",
  "change": 3.15,
  "change_percent": 1.30,
  "volume": 52847100,
  "market_cap": 3810000000000,
  "timestamp": "2026-07-06T14:30:00Z",
  "market_status": "open"
}

GET /crypto/price/:pair

获取加密货币对实时价格。

参数

参数	类型	必填	描述
`pair`	string (路径)	是	交易对，连字符分隔：`BTC-USD`、`ETH-USD`

响应

json

{
  "pair": "BTC-USD",
  "price": 105420.50,
  "change_24h": 2150.00,
  "change_percent_24h": 2.08,
  "high_24h": 106200.00,
  "low_24h": 102800.00,
  "volume_24h": 28500000000,
  "timestamp": "2026-07-06T14:30:00Z"
}

GET /fx/price/:pair

获取外汇对实时价格。

参数

参数	类型	必填	描述
`pair`	string (路径)	是	外汇对，连字符分隔：`EUR-USD`、`GBP-JPY`

响应

json

{
  "pair": "EUR-USD",
  "price": 1.0892,
  "bid": 1.0891,
  "ask": 1.0893,
  "spread": 0.0002,
  "change_24h": 0.0015,
  "timestamp": "2026-07-06T14:30:00Z"
}

GET /commodity/price/:symbol

获取大宗商品实时价格。

参数

参数	类型	必填	描述
`symbol`	string (路径)	是	商品代码，与交易对同为连字符格式：`XAU-USD`（黄金）、`XAG-USD`（白银）等

响应

json

{
  "symbol": "XAU-USD",
  "price": 4337.40,
  "unit": "troy ounce",
  "currency": "USD",
  "change": 12.50,
  "change_percent": 0.47,
  "timestamp": "2026-07-06T14:30:00Z"
}

代码示例

bash

# 美股实时价格
curl "https://api.jarvisclaw.ai/v1/marketplace/markets/stocks/us/price/AAPL" \
  -H "Authorization: Bearer sk-your-api-key"

# 加密货币 — $0.001
curl "https://api.jarvisclaw.ai/v1/marketplace/markets/crypto/price/BTC-USD" \
  -H "Authorization: Bearer sk-your-api-key"

# 外汇 — $0.001
curl "https://api.jarvisclaw.ai/v1/marketplace/markets/fx/price/EUR-USD" \
  -H "Authorization: Bearer sk-your-api-key"

# 大宗商品 — $0.001
curl "https://api.jarvisclaw.ai/v1/marketplace/markets/commodity/price/XAU-USD" \
  -H "Authorization: Bearer sk-your-api-key"

python

import requests

BASE = "https://api.jarvisclaw.ai/v1/marketplace/markets"
HEADERS = {"Authorization": "Bearer sk-your-api-key"}

# 1. 美股实时价格
resp = requests.get(f"{BASE}/stocks/us/price/AAPL", headers=HEADERS)
stock = resp.json()
print(f"AAPL: ${stock['price']:.2f} ({stock['change_percent']:+.2f}%)")

# 2. 加密货币 — $0.001
resp = requests.get(f"{BASE}/crypto/price/BTC-USD", headers=HEADERS)
btc = resp.json()
print(f"BTC: ${btc['price']:,.2f} (24h: {btc['change_percent_24h']:+.2f}%)")

# 3. 外汇 — $0.001
resp = requests.get(f"{BASE}/fx/price/EUR-USD", headers=HEADERS)
fx = resp.json()
print(f"EUR/USD: {fx['price']:.4f} (价差: {fx['spread']:.5f})")

# 4. 大宗商品 — $0.001
resp = requests.get(f"{BASE}/commodity/price/XAU-USD", headers=HEADERS)
gold = resp.json()
print(f"黄金: ${gold['price']:.2f}/{gold['unit']} ({gold['change_percent']:+.2f}%)")

python

from jarvisclaw import MarketplaceClient

# x402 Agent 钱包 — 每次调用自动支付 $0.001 USDC
client = MarketplaceClient(private_key="0x<evm-private-key>")

# 股票价格（付费 $0.001）
stock = client.call("markets", "/stocks/us/price/AAPL")
print(f"AAPL: ${stock['price']:.2f}")

# 加密 — $0.001，走 x402 结算
btc = client.call("markets", "/crypto/price/BTC-USD")
print(f"BTC: ${btc['price']:,.2f}")

# 外汇 — $0.001
eur = client.call("markets", "/fx/price/EUR-USD")
print(f"EUR/USD: {eur['price']:.4f}")

# 大宗商品 — $0.001
gold = client.call("markets", "/commodity/price/XAU-USD")
print(f"黄金: ${gold['price']:.2f}/{gold['unit']}")

package main

import (
    "context"
    "fmt"
    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()
    mc, _ := jc.NewMarketplaceClient(jc.WithAPIKey("sk-your-api-key"))

    // 美股价格
    stock, _ := mc.Call(ctx, "markets", "/stocks/us/price/AAPL")
    fmt.Printf("AAPL: $%.2f\n", stock["price"].(float64))

    // 加密货币 — $0.001
    btc, _ := mc.Call(ctx, "markets", "/crypto/price/BTC-USD")
    fmt.Printf("BTC: $%.2f\n", btc["price"].(float64))

    // 外汇 — $0.001
    eur, _ := mc.Call(ctx, "markets", "/fx/price/EUR-USD")
    fmt.Printf("EUR/USD: %.4f\n", eur["price"].(float64))

    // 大宗商品 — $0.001
    gold, _ := mc.Call(ctx, "markets", "/commodity/price/XAU-USD")
    fmt.Printf("黄金: $%.2f/%s\n", gold["price"].(float64), gold["unit"].(string))
}

package main

import (
    "context"
    "fmt"
    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()

    // x402 Agent — 每次调用自动付费 $0.001 USDC
    mc, _ := jc.NewMarketplaceClient(
        jc.WithPrivateKey("0x<agent-wallet-private-key>"),
    )

    // 股票价格（x402 自动支付）
    stock, _ := mc.Call(ctx, "markets", "/stocks/us/price/AAPL")
    fmt.Printf("AAPL: $%.2f\n", stock["price"].(float64))

    // 港股
    hk, _ := mc.Call(ctx, "markets", "/stocks/hk/price/0700")
    fmt.Printf("腾讯: HK$%.2f\n", hk["price"].(float64))

    // 加密同样按 $0.001 计费
    btc, _ := mc.Call(ctx, "markets", "/crypto/price/BTC-USD")
    fmt.Printf("BTC: $%.2f\n", btc["price"].(float64))
}

限制

只读数据 — 仅提供价格查询，不支持下单、交易执行或组合管理
无历史数据 — 仅提供实时/当前价格，无K线或历史回测数据
非投资建议 — 数据仅供参考，不构成买卖建议或加密货币交易策略
USD 计价 — 所有价格以美元返回，除非交易对/交易所另有指明
连字符分隔符必须 — 交易对使用连字符格式（BTC-USD、EUR-USD），不用斜杠（BTC/USD）
无盘前/盘后 — 股票仅提供常规交易时段数据
~400ms 刷新 — 预言机刷新延迟约 400 毫秒，非零延迟，不适合高频策略
无批量端点 — 只能逐个符号查询，没有 /batch 或 /list
并发上限 — 大量并行调用可能返回 429，退避后重试即可

错误

网关层错误是扁平结构 —— 只有一个 error 字符串：

json

{ "error": "service 'markets' is at capacity, please retry in a moment" }

HTTP	含义	处理
401	缺少或无效的 API Key / x402 签名	检查 `Authorization`，或让 SDK 重新签名
402	结算失败 —— 钱包无法支付上游	充值后重试
403	余额不足	充值，或检查你的支出限额
404	未知代码、市场或路径	对照支持的市场表核对
429	并发请求过多	退避后重试
502	上游价格源失败	重试
503	服务暂时不可用，或交易所休市	稍后重试

上游价格源自身的错误（代码不存在、交易对格式错误、休市）会原样透传。

交易市场 API ​

认证 ​

定价 ​

端点 ​

支持的交易所 ​

GET /stocks/:market/price/:symbol ​

参数 ​

响应 ​

GET /crypto/price/:pair ​

参数 ​

响应 ​

GET /fx/price/:pair ​

参数 ​

响应 ​

GET /commodity/price/:symbol ​

参数 ​

响应 ​

代码示例 ​

限制 ​

错误 ​

交易市场 API

认证

定价

端点

支持的交易所

GET /stocks/:market/price/:symbol

参数

响应

GET /crypto/price/:pair

参数

响应

GET /fx/price/:pair

参数

响应

GET /commodity/price/:symbol

参数

响应

代码示例

限制

错误