Typed GraphQL

Send a GraphQL request

Send POST https://api.stellaratlas.io/graphql with a JSON body containing query and variables. The GraphQL runner provides schema exploration and executable examples. Start with hubbleStatus for coverage and hubbleDatasets for dataset schemas.

Request application/json or application/graphql-response+json with Accept. Both can return HTTP 200 with GraphQL errors; inspect the response body as well as its status.

To call these fields from your application, copy the JavaScript request with a timeout and error handling. It checks HTTP and GraphQL errors and keeps partial data separate from a complete result.

Typed fields include hubbleTransaction, operations, assets, contracts, trades, offers, transfer activity, contract events, account balances and asset holders. Entity list/detail fields share the REST services and limits; changing interfaces does not change data coverage.

Read operations with typed fields

query Operations($input: HubbleOperationInput) {
  hubbleOperations(input: $input) {
    rows { id transactionHash sourceAccount type ledgerSequence details }
    window { minLedger maxLedger } coverageStatus semantics limit offset nextOffset
  }
}

Variables

{
  "input": {
    "minLedger": 63490364,
    "maxLedger": 63490365,
    "limit": 10,
    "offset": 0,
    "type": "payment"
  }
}

Set input.offset to the returned nextOffset with the other inputs unchanged; stop when it is null. This is offset pagination, not an input.after cursor. Operations link to their transaction by hash when the parsed relationship is available.

Inspect event classification

query ContractEvents($contractId: String!, $input: HubbleContractEventInput) {
  hubbleContractEvents(contractId: $contractId, input: $input) {
    contractId limit nextCursor
    items { id contractId ledgerSequence transactionHash type typeCode successful topicsJson dataJson classification { transactionKind eventKind sorobanExecutionEvidence provenance } }
    summary { total topics { topic count } }
    coverage { contiguousLastLedger maximumLedger gapCount }
    watermark { minimumLedger maximumLedger observedAt coverage }
  }
}

Variables

{
  "contractId": "CA526Y2NQWGWVVQ7RFFPGAZMU66PSYJ3UC2MTVAV4ZU7OM5BOPHDXUSG",
  "input": {
    "minLedger": 64877635,
    "maxLedger": 64877698,
    "typeCode": 1,
    "topic": "REDSTONE",
    "order": "desc",
    "includeSummary": true,
    "limit": 2
  }
}

Keep nextCursor and the original event filters together. Topics and data are decoded JSON strings; classification explains the execution evidence and its provenance.

Read balance observations

query AccountBalances($account: String!, $input: HubbleAccountBalanceInput) {
  hubbleAccountBalances(account: $account, input: $input) {
    account balanceScope limit nextCursor
    balances { asset balance amountPrecision balanceRaw observedLedger lastModifiedLedger }
    coverage { contiguousLastLedger maximumLedger gapCount }
    watermark { mode catalogGeneratedAt catalogMaximumLedger snapshotPinned }
  }
}

Variables

{
  "account": "GCX7LOMYJM54CXJPNTDZPMFSTQTQJTR5XR4DKZXLSWJG3R4B7GOADWXZ",
  "input": {
    "limit": 10
  }
}

balanceScope and watermark identify the latest-ingested interpretation. A missing raw value is not zero, and this response is not an arbitrary-ledger state witness.

Use structured dataset queries for aggregation

hubbleQuery provides schema-driven dataset selection, filters and grouped metrics. Its dynamic rows use JSON because the selected dataset determines the columns; typed entity fields remain separate. Grouped metric functions use COUNT, COUNT_DISTINCT, SUM, AVG, MIN and MAX.

Run the “Analytics: count operations by type” example in the query runner. Check metric precision metadata and coverage, and keep each request bounded rather than issuing many expensive aliases at once.