GraphQL 엔드포인트
모든 GraphQL 쿼리는 단일 엔드포인트로 전송됩니다:
https://graphql.chainstream.io/graphql
| 메서드 | Content-Type | 사용 사례 |
|---|
POST | application/json | 모든 쿼리에 권장 — 변수와 복잡한 쿼리 지원 |
GET | 쿼리 문자열 (?query=...) | 간단한 쿼리, 브라우저 테스트, 캐싱 친화적 |
프로덕션 워크로드에는 POST를 사용하세요. GET 요청은 쿼리를 URL에 인코딩하므로 길이 제한이 있고 복잡한 쿼리가 다루기 어려워집니다.
X-API-KEY 헤더에 API Key를 전달하여 인증합니다. REST Data API와 동일한 API Key를 사용하므로 별도의 자격 증명이 필요하지 않습니다.
필수 헤더
| 헤더 | 값 | 필수 |
|---|
Content-Type | application/json | 예 (POST) |
X-API-KEY | cs_live_... | 예 |
요청 형식
GraphQL 요청 본문은 두 개의 필드를 가진 JSON 객체입니다:
| 필드 | 타입 | 설명 |
|---|
query | string | GraphQL 쿼리 또는 뮤테이션 문자열 |
variables | object | $variable 구문으로 쿼리에서 참조되는 선택적 변수 |
POST 예제
cURL
cURL (쿼리 파일)
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": "query ($network: Network!) { DEXTrades(network: $network, limit: {count: 5}) { Block { Time } Trade { Buy { Currency { MintAddress } Amount } } } }",
"variables": { "network": "sol" }
}'
복잡한 쿼리의 경우 쿼리를 파일에 저장하고 참조할 수 있습니다:# 쿼리를 파일에 저장
cat > query.graphql << 'EOF'
query ($network: Network!) {
DEXTrades(network: $network, limit: {count: 5}) {
Block { Time }
Trade {
Buy {
Currency { MintAddress }
Amount
}
}
}
}
EOF
# 변수와 함께 전송
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' ' ')\", \"variables\": {\"network\": \"sol\"}}"
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: `query ($network: Network!) {
DEXTrades(network: $network, limit: {count: 5}) {
Block { Time }
Trade { Buy { Currency { MintAddress } Amount } }
}
}`,
variables: { network: "sol" },
}),
});
const { data, extensions } = await response.json();
console.log(data.DEXTrades);
import requests
resp = requests.post(
"https://graphql.chainstream.io/graphql",
headers={
"Content-Type": "application/json",
"X-API-KEY": "your_api_key",
},
json={
"query": """query ($network: Network!) {
DEXTrades(network: $network, limit: {count: 5}) {
Block { Time }
Trade { Buy { Currency { MintAddress } Amount } }
}
}""",
"variables": {"network": "sol"},
},
)
data = resp.json()
print(data["data"]["DEXTrades"])
GET 예제
curl -G "https://graphql.chainstream.io/graphql" \
-H "X-API-KEY: your_api_key" \
--data-urlencode 'query={ DEXTrades(network: sol, limit: {count: 5}) { Block { Time } } }'
지원 네트워크
모든 최상위 Cube 쿼리에서 network 인자를 열거형 값으로 전달하세요:
| Network 열거형 | 블록체인 | Chain ID |
|---|
sol | Solana | — |
eth | Ethereum | 1 |
bsc | BNB Chain (BSC) | 56 |
# Solana
{ DEXTrades(network: sol, limit: {count: 5}) { ... } }
# Ethereum
{ DEXTrades(network: eth, limit: {count: 5}) { ... } }
# BSC
{ DEXTrades(network: bsc, limit: {count: 5}) { ... } }
응답 형식
모든 응답은 다음 구조의 JSON입니다:
{
"data": {
"DEXTrades": [
{ "Block": { "Time": "2025-03-27T10:15:30Z" }, "..." : "..." }
]
},
"extensions": {
"credits": {
"total": 50,
"cubes": [
{ "cube": "DEXTrades", "credits": 50, "row_count": 5 }
]
}
}
}
| 필드 | 설명 |
|---|
data | 쿼리 결과 — 쿼리의 형태와 일치 |
errors | 유효성 검사 또는 실행 오류가 있을 때만 존재 |
extensions.credits.total | 이 쿼리에서 소비된 총 크레딧 단위 |
extensions.credits.cubes | Cube별 상세: Cube 이름, 부과된 크레딧, 반환된 행 수 |
extensions.credits 필드는 크레딧이 소비될 때 포함됩니다. 크레딧 계산 방법에 대한 자세한 내용은 빌링 & 크레딧을 참조하세요.오류 응답
쿼리가 잘못되었거나 실패하면 응답에 errors 배열이 포함됩니다:
{
"data": null,
"errors": [
{
"message": "Unknown field 'InvalidField' on type 'DEXTrades'",
"locations": [{ "line": 3, "column": 5 }]
}
]
}
애플리케이션에 통합하기 전에 GraphQL IDE를 사용하여 쿼리를 인터랙티브하게 검증하세요. IDE는 자동 완성과 인라인 오류 강조 기능을 제공합니다.
다음 단계
첫 번째 쿼리 실행
IDE 또는 cURL에서 실제 쿼리를 실행하는 단계별 튜토리얼을 따라해 보세요.
스키마 탐색
25개 Cube, 필드 타입, 필터링 연산자, 집계 함수를 살펴보세요.
