端点与认证

GraphQL 端点

所有 GraphQL 查询发往同一端点：

https://graphql.chainstream.io/graphql

同时支持 POST 与 GET。

Method	Content-Type	使用场景
`POST`	`application/json`	推荐用于所有查询 —— 支持 variables 与复杂查询
`GET`	查询字符串（`?query=...`）	简单查询、浏览器测试、利于缓存

生产环境请使用 POST。GET 将查询编码在 URL 中，存在长度限制，复杂查询不便使用。

认证

在 X-API-KEY 请求头中传入 API Key 即可完成认证。与 REST Data API 使用同一 API Key，无需单独凭证。

X-API-KEY: your_api_key

在 ChainStream Dashboard → Applications → Create New App 获取 API Key。Key 以 cs_live_... 开头。

必填请求头

Header	Value	是否必填
`Content-Type`	`application/json`	是（POST）
`X-API-KEY`	`cs_live_...`	是

请求格式

GraphQL 请求体为包含两个字段的 JSON 对象：

Field	Type	说明
`query`	`string`	GraphQL query 或 mutation 字符串
`variables`	`object`	可选，在查询中通过 `$variable` 语法引用的变量

POST 示例

cURL
cURL (query file)
JavaScript (fetch)
Python (requests)

curl -X POST "https://graphql.chainstream.io/graphql" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d '{
    "query": "{ Solana { DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) { Block { Time } Trade { Buy { Currency { MintAddress } Amount } } } } }"
  }'

复杂查询可保存为文件再引用：

# Save query to file
cat > query.graphql << 'EOF'
{
  Solana {
    DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
      Block { Time }
      Trade {
        Buy {
          Currency { MintAddress }
          Amount
        }
      }
    }
  }
}
EOF

# Send request
curl -X POST "https://graphql.chainstream.io/graphql" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -d "{\"query\": \"$(cat query.graphql | tr '\n' ' ')\"}"

const response = await fetch("https://graphql.chainstream.io/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
  },
  body: JSON.stringify({
    query: `{
      Solana {
        DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
          Block { Time }
          Trade { Buy { Currency { MintAddress } Amount } }
        }
      }
    }`,
  }),
});

const { data, extensions } = await response.json();
console.log(data.Solana.DEXTrades);

import requests

resp = requests.post(
    "https://graphql.chainstream.io/graphql",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "your_api_key",
    },
    json={
        "query": """{
            Solana {
                DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) {
                    Block { Time }
                    Trade { Buy { Currency { MintAddress } Amount } }
                }
            }
        }""",
    },
)

data = resp.json()
print(data["data"]["Solana"]["DEXTrades"])

GET 示例

curl -G "https://graphql.chainstream.io/graphql" \
  -H "X-API-KEY: your_api_key" \
  --data-urlencode 'query={ Solana { DEXTrades(limit: {count: 5}, orderBy: {descending: Block_Time}) { Block { Time } } } }'

支持的网络

将 Cube 查询包裹在对应的 Chain Group 中以选择网络：

Chain Group	Blockchain	Chain ID
`Solana`	Solana	—
`EVM(network: eth)`	Ethereum	1
`EVM(network: bsc)`	BNB Chain (BSC)	56

# Solana
{ Solana { DEXTrades(limit: {count: 5}) { ... } } }

# Ethereum
{ EVM(network: eth) { DEXTrades(limit: {count: 5}) { ... } } }

# BSC
{ EVM(network: bsc) { DEXTrades(limit: {count: 5}) { ... } } }

响应格式

所有响应均为 JSON，结构如下：

{
  "data": {
    "Solana": {
      "DEXTrades": [
        { "Block": { "Time": "2025-03-27T10:15:30Z" }, "..." : "..." }
      ]
    }
  },
  "extensions": {
    "credits": {
      "total": 50,
      "cubes": [
        { "cube": "DEXTrades", "credits": 50, "row_count": 5 }
      ]
    }
  }
}

Field	说明
`data`	查询结果 —— 与查询结构一致
`errors`	仅在存在校验或执行错误时出现
`extensions.credits.total`	本次查询消耗的 credit 单位总计
`extensions.credits.cubes`	按 Cube 拆分：Cube 名称、计费 credits 与返回行数

在产生 credits 消耗时，响应会包含 extensions.credits 字段。Credits 计算方式见计费与额度。

错误响应

当查询格式错误或执行失败时，响应会包含 errors 数组：

{
  "data": null,
  "errors": [
    {
      "message": "Unknown field 'InvalidField' on type 'DEXTrades'",
      "locations": [{ "line": 3, "column": 5 }]
    }
  ]
}

在接入应用前，可使用 GraphQL IDE 交互式校验查询。IDE 提供自动补全与行内错误高亮。

快速开始

GraphQL IDE

Schema 与数据模型

查询示例

计费与额度

GraphQL 端点

认证

必填请求头

请求格式

POST 示例

GET 示例

支持的网络

响应格式

错误响应

下一步

运行首次查询

探索 Schema

​GraphQL 端点

​认证

​必填请求头

​请求格式

​POST 示例

​GET 示例

​支持的网络

​响应格式

​错误响应

​下一步

运行首次查询

探索 Schema

GraphQL 端点

认证

必填请求头

请求格式

POST 示例

GET 示例

支持的网络

响应格式

错误响应

下一步