chainstream-graphql Skill

개요

chainstream-graphql 스킬은 AI 에이전트에게 GraphQL을 통한 ChainStream 온체인 데이터 웨어하우스에 대한 유연한 SQL 유사 접근을 제공합니다. 사전 구축된 REST/MCP 엔드포인트로 표현력이 부족할 때 — 큐브 간 JOIN, 커스텀 집계, 다중 조건 필터, 커스텀 시계열 해상도, 또는 GraphQL로만 노출된 데이터(예: PolyMarket 예측 큐브) — 적합한 도구입니다.

패턴: Tool (읽기 전용, 서명 불필요)
엔드포인트: https://graphql.chainstream.io/graphql (APISIX 경유)
CLI: npx @chainstream-io/cli graphql
인증: X-API-KEY를 통한 API Key 또는 SIWX 지갑 토큰
결제: REST와 동일한 API Key / 구독 풀 (CLI가 x402 / MPP 자동 처리)
범위: 3개 체인 그룹에 걸친 27개 큐브 — Solana, EVM(network: eth | bsc | polygon), Trading

사용 시점

chainstream-data와의 결정 매트릭스:

시나리오	사용	이유
표준 토큰 검색, 시장 트렌딩, 지갑 프로필	`chainstream-data`	사전 구축된 REST / MCP 엔드포인트, 더 간단
큐브 간 JOIN (trades + transfers, pools + events)	chainstream-graphql	`joinXxx` 지원
커스텀 집계 (`groupBy`와 함께 count / sum / avg)	chainstream-graphql	메트릭 + 차원 그룹화
다중 조건 필터 (중첩, `any`를 통한 OR)	chainstream-graphql	전체 필터 연산자 세트
커스텀 해상도 / 버킷의 시계열	chainstream-graphql	시간 구간 버킷팅
예측 시장 데이터 (Polygon의 PolyMarket)	chainstream-graphql	`PredictionTrades / Managements / Settlements` 큐브

통합 경로

채널 매트릭스

GraphQL은 서로 다른 호출자로부터 접근되는 단일 표면입니다:

작업	CLI 명령어	SDK 메서드
전체 큐브 조회 (요약)	`graphql schema --summary`	N/A — 탐색에는 CLI 사용
하나의 큐브 상세 조회	`graphql schema --type <CubeName>`	N/A
전체 스키마 레퍼런스	`graphql schema --full`	N/A
캐시된 스키마 강제 새로고침	`graphql schema --summary --refresh`	N/A
인라인 쿼리	`graphql query --query '<gql>'`	`client.graphql.query(gql)`
파일에서 쿼리	`graphql query --file ./q.graphql`	`client.graphql.query(fs.readFileSync(...))`
변수 포함 쿼리	`graphql query --query '...' --var '{"k":"v"}'`	`client.graphql.query(gql, vars)`
머신 판독 출력	`--json` 추가	네이티브 JSON 반환

AI 워크플로우

스키마 탐색

에이전트가 어떤 큐브가 필요한지 아직 모른다면 항상 여기서 시작하세요.

npx @chainstream-io/cli graphql schema --summary
npx @chainstream-io/cli graphql schema --type DEXTrades

--summary는 체인(EVM / Solana / Trading)별로 그룹화된 27개 큐브의 압축 카탈로그를 최상위 필드와 설명과 함께 반환합니다. --type은 쿼리 구성을 위해 하나의 큐브 필드 트리를 확장합니다.

쿼리 작성 및 실행

스키마는 최상위 진입점으로 체인 그룹 래퍼를 사용합니다.

Solana
EVM
Trading

query {
  Solana {
    DEXTrades(
      limit: { count: 25 }
      orderBy: { descending: Block_Time }
    ) {
      Block { Time }
      Trade {
        Buy  { Currency { MintAddress } Amount PriceInUSD }
        Sell { Currency { MintAddress } Amount }
        Dex  { ProtocolName }
      }
    }
  }
}

query {
  EVM(network: eth) {
    DEXTrades(
      limit: { count: 25 }
      orderBy: { descending: Block_Time }
      where: { Trade: { Buy: { Amount: { gt: "0" } } } }
    ) {
      Block { Time }
      Trade { Buy { Currency { Symbol } Amount } Sell { Currency { Symbol } Amount } }
    }
  }
}

query {
  Trading {
    Pairs(
      tokenAddress: { is: "So11111111111111111111111111111111111111112" }
      limit: { count: 24 }
    ) {
      TimeMinute
      Price { Open High Low Close }
    }
  }
}

CLI로 실행:

npx @chainstream-io/cli graphql query --file ./query.graphql --json

또는 인라인:

npx @chainstream-io/cli graphql query \
  --query 'query { Solana { DEXTrades(limit:{count:5}) { Block { Time } } } }' \
  --json

쿼리 작성 빠른 레퍼런스

체인 그룹 래퍼: 최상위 필수. Solana, EVM(network: ...), 또는 Trading.
network: EVM에만 적용. 값: eth, bsc, polygon.
limit: { count: N, offset: M }. 기본 25.
orderBy: { descending: Field } / { ascending: Field }. 계산된 필드에는 { descendingByField: "field_name" }.
where: { Group: { Field: { operator: value } } }. OR 조건은 any: [{...}, {...}].
DateTime 형식: "YYYY-MM-DD HH:MM:SS" — T 없음, Z 없음 (ClickHouse 요구 사항).
DateTime 필터: since, till, after, before — DateTime 필드에는 절대 gt / lt 사용 금지.
joinXxx: 관련 큐브에 대한 LEFT JOIN. 여러 쿼리보다 우선.
dataset 래퍼 인자: realtime, archive, combined (기본).
aggregates 래퍼 인자: yes, no, only.

체인 그룹과 큐브

체인 그룹	래퍼	큐브
Solana	`Solana { ... }`	DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPools, Instructions, InstructionBalanceUpdates, Rewards, DEXOrders, TokenSupplyUpdates
EVM	`EVM(network: eth\|bsc\|polygon) { ... }`	DEXTrades, DEXTradeByTokens, Transfers, BalanceUpdates, Blocks, Transactions, DEXPoolEvents, Events, Calls, MinerRewards, DEXPoolSlippages, TokenHolders, TransactionBalances, Uncles, PredictionTrades, PredictionManagements, PredictionSettlements*
Trading	`Trading { ... }`	Pairs, Tokens, Currencies, Trades

* 예측 큐브는 polygon 네트워크에서만 사용 가능.

안전 규칙

이 규칙들은 쿼리의 정확성을 유지하고 쿼터 낭비를 피하기 위해 스킬에 의해 강제 적용됩니다.

규칙	이유
평면 `CubeName(network: sol)` 사용 금지 — 항상 체인 그룹에 래핑	서버가 래핑되지 않은 쿼리 거부
필드 이름 추측 금지 — 먼저 `graphql schema --type <cube>` 실행	”필드가 존재하지 않습니다” 오류의 왕복 절약
ISO-8601 `"2026-03-31T00:00:00Z"` 사용 금지 — `"2026-03-31 00:00:00"` 사용	ClickHouse DateTime 형식
DateTime에 `gt` / `lt` 사용 금지 — `since` / `after` / `before` / `till` 사용	DateTime 필터는 이름 지정됨
`joinXxx`로 결합 가능한 관련 데이터를 여러 쿼리로 분리 금지	여러 건 대신 한 번의 과금 요청
결제 플랜 자동 선택 금지 — 항상 사용자가 선택	청구 동의

오류 복구

오류	복구 방법
401 / “Not authenticated”	`config auth` — 로그인되지 않은 경우 `login` 실행 (nano trial 자동 지급, 50K CU). 그 후 재시도.
402 / “Payment required”	`plan status`; 활성 구독이 없으면 `wallet pricing` → `plan purchase --plan <choice>`. x402 결제를 참고하세요.
`GraphQL error: field X does not exist`	`graphql schema --type <cube>`에 대해 필드 재확인.
429	1초 대기, 지수 백오프.
5xx	2초 후 1회 재시도.

chainstream-data

토큰, 시장, 지갑 분석용 표준 REST/MCP 쿼리

chainstream-defi

분석 후 트레이딩 실행 — 스왑, 토큰 생성

GraphQL 접근 방식

엔드포인트 레퍼런스, 인증, 스키마 개요

CLI `graphql` 서브명령

chainstream graphql schema 및 query 레퍼런스

데이터 제품

접속 방법

AI Agents

컴플라이언스 (KYT/KYA)

튜토리얼

레시피

플랫폼

에코시스템

레퍼런스

chainstream-graphql Skill

개요

사용 시점

통합 경로

채널 매트릭스

AI 워크플로우

스키마 탐색

쿼리 작성 및 실행

쿼리 작성 빠른 레퍼런스

체인 그룹과 큐브

안전 규칙

오류 복구

관련 문서

chainstream-data

chainstream-defi

GraphQL 접근 방식

CLI `graphql` 서브명령

데이터 제품

접속 방법

AI Agents

컴플라이언스 (KYT/KYA)

튜토리얼

레시피

플랫폼

에코시스템

레퍼런스

​개요

​사용 시점

​통합 경로

​채널 매트릭스

​AI 워크플로우

​스키마 탐색

​쿼리 작성 및 실행

​쿼리 작성 빠른 레퍼런스

​체인 그룹과 큐브

​안전 규칙

​오류 복구

​관련 문서

chainstream-data

chainstream-defi

GraphQL 접근 방식

CLI `graphql` 서브명령

개요

사용 시점

통합 경로

채널 매트릭스

AI 워크플로우

스키마 탐색

쿼리 작성 및 실행

쿼리 작성 빠른 레퍼런스

체인 그룹과 큐브

안전 규칙

오류 복구

관련 문서