schema {
query: QueryRoot
mutation: MutationRoot
subscription: SubscriptionRoot
}
"""
Readiness state of the API server
"""
enum ReadinessState {
"The server is not ready to serve general GraphQL traffic yet"
NOT_READY
"The server is ready to serve GraphQL traffic"
READY
}
"""
Account information
The Account type contains identity information for HOPR nodes including keys,
addresses, and network announcements. To query balances and allowances, use the
dedicated balance and allowance queries (hoprBalance, nativeBalance, safeHoprAllowance).
"""
type Account {
"Unique account on-chain address in hexadecimal format"
chainKey: String!
"Unique identifier for the account"
keyid: Int!
"Latest announced multiaddress for the packet key, returned as an empty or single-element list"
multiAddresses: [String!]!
"Unique account packet key in peer id format"
packetKey: String!
"HOPR Safe contract address to which the account is linked (null if no Safe is linked)"
safeAddress: String
}
"""
Success response for accounts query
"""
type AccountsList {
"List of accounts"
accounts: [Account!]!
}
"""
Result type for accounts list query
"""
union AccountsResult = AccountsList | MissingFilterError | QueryFailedError
"""
Result type for module address calculation
"""
union CalculateModuleAddressResult =
| ModuleAddress
| InvalidAddressError
| QueryFailedError
"""
Blockchain and HOPR network information
"""
type ChainInfo {
"Current block number of the blockchain"
blockNumber: Int!
"Chain ID of the connected blockchain network"
chainId: Int!
"Channel closure grace period in seconds"
channelClosureGracePeriod: UInt64!
"Channel smart contract domain separator (hex string)"
channelDst: String
"Map of contract identifiers to their deployed addresses"
contractAddresses: ContractAddressMap!
"Expected block time in seconds"
expectedBlockTime: UInt64!
"Number of block confirmations required for finality"
finality: UInt64!
"Estimated legacy gas price in wei from RPC"
gasPrice: String
"Current key binding fee"
keyBindingFee: TokenValueString!
"Ledger smart contract domain separator (hex string)"
ledgerDst: String
"Estimated EIP-1559 max fee per gas in wei from RPC, scaled by api.gas_multiplier"
maxFeePerGas: String
"Estimated EIP-1559 max priority fee per gas in wei from RPC, scaled by api.gas_multiplier"
maxPriorityFeePerGas: String
"Current minimum ticket winning probability (decimal value between 0.0 and 1.0)"
minTicketWinningProbability: Float!
"Network name (e.g., 'rotsee', 'jura')"
network: String!
"Safe Registry smart contract domain separator (hex string)"
safeRegistryDst: String
"Current HOPR token price"
ticketPrice: TokenValueString!
}
"""
Result type for chain info queries
"""
union ChainInfoResult = ChainInfo | QueryFailedError
"""
Payment channel between two nodes
"""
type Channel {
"Total amount of HOPR tokens allocated to the channel"
balance: TokenValueString!
"Timestamp when the channel closure was initiated (null if no closure initiated)"
closureTime: DateTime
"Unique identifier for the payment channel in hexadecimal format"
concreteChannelId: String!
"Account keyid of the destination node"
destination: Int!
"Current epoch of the channel (uint24)"
epoch: Int!
"Account keyid of the source node"
source: Int!
"Current state of the channel (OPEN, PENDINGTOCLOSE, or CLOSED)"
status: ChannelStatus!
"Latest ticket index used in the channel (uint48, max: 281474976710655)"
ticketIndex: UInt64!
}
"""
Success response for channels query
"""
type ChannelsList {
"List of channels"
channels: [Channel!]!
}
"""
Result type for channels list query
"""
union ChannelsResult =
| ChannelsList
| InvalidAddressError
| MissingFilterError
| QueryFailedError
"""
Aggregated channel statistics: count and total wxHOPR balance
"""
type ChannelStats {
"Total wxHOPR balance across all matching channels"
balance: TokenValueString!
"Number of channels matching the filters"
count: Int!
}
"""
Result type for channel statistics query
"""
union ChannelStatsResult = ChannelStats | InvalidAddressError | QueryFailedError
"""
Status of a payment channel
"""
enum ChannelStatus {
"Channel has been closed"
CLOSED
"Channel is open and operational"
OPEN
"Channel is in the process of closing"
PENDINGTOCLOSE
}
"""
Compatibility contract for blokli-client consumers
"""
type Compatibility {
"The blokli-api package version serving this schema"
apiVersion: String!
"Feature flags exposed by this server, e.g. indexes_safe_events"
features: [String!]!
"Semver requirement describing which blokli-client versions are supported"
supportedClientVersions: String!
}
"""
Map of contract identifier to contract address (hexadecimal format).
Keys: token, channels, announcements, module_implementation, node_safe_migration, node_safe_registry, ticket_price_oracle, winning_probability_oracle, node_stake_factory
Example: {"token": "0x123...", "channels": "0x456...", "node_safe_registry": "0x789..."}
"""
scalar ContractAddressMap
"""
Target contract not in allowlist
"""
type ContractNotAllowedError {
"Error code"
code: String!
"Contract address that was rejected"
contractAddress: String!
"Human-readable error message"
message: String!
}
"""
Success response for count queries
"""
type Count {
"Count value"
count: Int!
}
"""
Result type for count queries
"""
union CountResult = Count | MissingFilterError | QueryFailedError
"""
ISO 8601 datetime string (e.g., "2024-01-15T10:30:00Z")
"""
scalar DateTime
"""
Function selector not allowed
"""
type FunctionNotAllowedError {
"Error code"
code: String!
"Contract address"
contractAddress: String!
"Function selector that was rejected"
functionSelector: String!
"Human-readable error message"
message: String!
}
"""
32-byte value as 64-character hexadecimal string (with or without 0x prefix)
"""
scalar Hex32
"""
HOPR token balance information for a specific address
"""
type HoprBalance {
"Address holding the HOPR token balance"
address: String!
"HOPR token balance"
balance: TokenValueString!
}
"""
Result type for HOPR balance queries
"""
union HoprBalanceResult = HoprBalance | InvalidAddressError | QueryFailedError
"""
Address format is invalid
"""
type InvalidAddressError {
"The invalid address that was provided"
address: String!
"Error code"
code: String!
"Human-readable error message"
message: String!
}
"""
Transaction ID format is invalid
"""
type InvalidTransactionIdError {
"Error code"
code: String!
"Human-readable error message"
message: String!
"The invalid transaction ID that was provided"
transactionId: String!
}
"""
Required filter parameter(s) not provided
"""
type MissingFilterError {
"Error code"
code: String!
"Human-readable error message"
message: String!
}
"""
Calculated module address
"""
type ModuleAddress {
"Predicted module address (hexadecimal format)"
moduleAddress: String!
}
"""
Root mutation type providing transaction submission capabilities
"""
type MutationRoot {
"""
Submit a transaction with fire-and-forget mode
Validates the pre-signed raw transaction data and submits it to the chain.
Returns the transaction hash immediately after submission.
Does not wait for confirmation and does not track transaction status.
Use this mode for maximum performance when you don't need confirmation tracking.
"""
sendTransaction(
"Transaction data to submit"
input: TransactionInput!
): SendTransactionResult!
"""
Submit a transaction asynchronously
Validates the pre-signed raw transaction data and submits it to the chain immediately.
Returns the transaction ID that can be used to query status later.
Does not wait for on-chain confirmation. Background monitor tracks confirmation.
"""
sendTransactionAsync(
"Transaction data to submit"
input: TransactionInput!
): SendTransactionAsyncResult!
"""
Submit a transaction synchronously
Validates the pre-signed raw transaction data, submits it to the chain, and waits for
the specified number of confirmations (default: 3 blocks) before returning.
Transaction can be queried later.
"""
sendTransactionSync(
"Number of block confirmations to wait for (default: 3, max: 64)"
confirmations: Int
"Transaction data to submit"
input: TransactionInput!
): SendTransactionSyncResult!
}
"""
Native token balance information for a specific address
"""
type NativeBalance {
"Address holding the native token balance"
address: String!
"Native token balance"
balance: TokenValueString!
}
"""
Result type for native balance queries
"""
union NativeBalanceResult =
| NativeBalance
| InvalidAddressError
| QueryFailedError
"""
A single edge in the opened payment channels graph
Represents one channel with its associated source and destination accounts.
This is a directed edge: source → destination. If channels exist in both
directions (A→B and B→A), these are emitted as separate entries.
**Structure:**
- Each entry contains exactly one channel with its source and destination accounts
- If multiple channels exist between the same account pair, each is emitted as a separate entry
- Initial snapshot entries are always open; subsequent update entries may include
non-open states such as CLOSED
**Usage in subscriptions:**
The `openedChannelGraphUpdated` subscription streams these entries one at a time.
Clients must accumulate entries by `channel.concreteChannelId` to build the
complete channel graph. An entry is emitted whenever that specific channel is
updated. CLOSED entries are intentional removal signals for consumers that
maintain an open-channel graph.
"""
type OpenedChannelsGraphEntry {
"The payment channel update from source to destination"
channel: Channel!
"Destination account (recipient end of the directed edge)"
destination: Account!
"Source account (sender end of the directed edge)"
source: Account!
}
"""
Internal query error
"""
type QueryFailedError {
"Error code"
code: String!
"Human-readable error message"
message: String!
}
"""
Root query type providing read-only access to indexed blockchain data
"""
type QueryRoot {
"""
Count accounts matching optional filters
If no filters are provided, returns total account count.
Filters can be combined to narrow results.
Returns Error if query fails.
"""
accountCount(
"Filter by chain key (hexadecimal format)"
chainKey: String
"Filter by account keyid"
keyid: Int
"Filter by packet key (peer ID format)"
packetKey: String
): CountResult!
"""
Retrieve accounts with required filtering
**At least one filter parameter must be provided** (keyid, packetKey, or chainKey).
Returns Error with code MISSING_REQUIRED_FILTER if no filters are specified.
Filters can be combined to narrow results further.
Example: accounts(keyid: 1) or accounts(chainKey: "0x1234...")
"""
accounts(
"Filter by chain key (hexadecimal format)"
chainKey: String
"Filter by account keyid"
keyid: Int
"Filter by packet key (peer ID format)"
packetKey: String
): AccountsResult!
"""
Calculate the predicted module address for a Safe deployment
Calls the HoprNodeStakeFactory.predictModuleAddress_1 function to compute
the deterministic CREATE2 address for a HOPR node management module.
The channels contract address and capability permissions are automatically
obtained from the system configuration.
Returns Error with code INVALID_ADDRESS if owner or safeAddress format is invalid.
Returns Error with code QUERY_FAILED if RPC call fails.
"""
calculateModuleAddress(
"Safe deployment nonce"
nonce: UInt64!
"Safe owner address (hexadecimal format)"
owner: String!
"Predicted Safe contract address (hexadecimal format)"
safeAddress: String!
): CalculateModuleAddressResult!
"""
Retrieve chain information
"""
chainInfo: ChainInfoResult!
"""
Count channels matching optional filters
If no filters are provided, returns total channels count.
Filters can be combined to narrow results.
Returns Error if query fails.
**Deprecated**: Use `channelStats` instead, which also returns the total wxHOPR balance.
"""
channelCount(
"Filter by concrete channel ID (hexadecimal format)"
concreteChannelId: String
"Filter by destination node keyid"
destinationKeyId: Int
"Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)"
safeAddress: String
"Filter by source node keyid"
sourceKeyId: Int
"Filter by channel status"
status: ChannelStatus
): CountResult!
@deprecated(
reason: "Use channelStats instead, which also returns the total wxHOPR balance."
)
"""
Retrieve channel count and total wxHOPR balance matching optional filters
If no filters are provided, returns stats across all channels.
The safeAddress filter restricts results to channels where the source account is associated
with the given safe contract.
Filters can be combined to narrow results further.
Returns Error with code INVALID_ADDRESS if safeAddress format is invalid.
"""
channelStats(
"Filter by concrete channel ID (hexadecimal format)"
concreteChannelId: String
"Filter by destination node keyid"
destinationKeyId: Int
"Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)"
safeAddress: String
"Filter by source node keyid"
sourceKeyId: Int
"Filter by channel status"
status: ChannelStatus
): ChannelStatsResult!
"""
Retrieve channels with required filtering
**At least one identity filter must be provided** (sourceKeyId, destinationKeyId, concreteChannelId, or safeAddress).
The status filter is optional and can be used in combination with identity filters.
The safeAddress filter restricts results to channels where the source account is associated
with the given safe contract.
Returns Error with code INVALID_ADDRESS if safeAddress format is invalid.
Returns Error with code MISSING_REQUIRED_FILTER if no identity filters are specified.
Filters can be combined to narrow results further.
Example: channels(sourceKeyId: 1) or channels(safeAddress: "0x...") or channels(sourceKeyId: 1, status: OPEN)
"""
channels(
"Filter by concrete channel ID (hexadecimal format)"
concreteChannelId: String
"Filter by destination node keyid"
destinationKeyId: Int
"Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)"
safeAddress: String
"Filter by source node keyid"
sourceKeyId: Int
"Filter by channel status (optional, combine with identity filters)"
status: ChannelStatus
): ChannelsResult!
"""
Client compatibility information
Returns the API version and a semver requirement for compatible blokli-client releases.
"""
compatibility: Compatibility!
"""
Health check endpoint
Returns "ok" to indicate the service is running
"""
health: String!
"""
Retrieve HOPR token balance for a specific address
This query can be used to get balances for any on-chain address, including:
- Account chain keys (Account.chainKey)
- Safe contract addresses (Account.safeAddress)
- Any other Ethereum-compatible address
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if no balance exists for the address.
Example (querying a Safe balance requires two separate requests):
```graphql
# Request 1: Get the account's Safe address
query GetAccount {
accounts(keyid: 1) {
... on AccountsList {
accounts {
safeAddress
}
}
}
}
# Request 2: Query the Safe's HOPR balance using address from first response
query GetSafeHoprBalance($safeAddress: String!) {
hoprBalance(address: $safeAddress, token: HOPR) {
... on HoprBalance {
address
balance
}
}
}
```
"""
hoprBalance(
"On-chain address to query (hexadecimal format)"
address: String!
"HOPR token to query: HOPR (default) or XHOPR. NATIVE is not accepted here — use nativeBalance instead."
token: Token = HOPR
): HoprBalanceResult!
"""
Retrieve native token balance for a specific address
This query can be used to get balances for any on-chain address, including:
- Account chain keys (Account.chainKey)
- Safe contract addresses (Account.safeAddress)
- Any other Ethereum-compatible address
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if no balance exists for the address.
"""
nativeBalance(
"On-chain address to query (hexadecimal format)"
address: String!
): NativeBalanceResult!
"""
Retrieve safe by contract address
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if safe is not found.
"""
safe(
"Safe contract address to query (hexadecimal format)"
address: String!
): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Retrieve safe by selector.
The selector enum identifies the lookup type using the provided selected address.
"""
safeBy(
"Address for the selector (hexadecimal format)"
address: String!
"Selector type for safe lookup"
selector: SafeSelectorInput!
): SafeByResult
"""
Retrieve safe by chain key (owner address)
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if safe is not found.
"""
safeByChainKey(
"Chain key to query (hexadecimal format)"
chainKey: String!
): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Retrieve safe by registered node address
Returns the safe that a given node is registered to.
Returns Error with code INVALID_ADDRESS if chainKey format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if node is not registered to any safe.
"""
safeByRegisteredNode(
"Node chain key to query (hexadecimal format)"
chainKey: String!
): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Retrieve Safe HOPR token allowance for a specific Safe address
This query returns the wxHOPR token allowance that the specified Safe contract
has granted to the HOPR channels contract.
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if no allowance data exists for the address.
"""
safeHoprAllowance(
"Safe contract address to query (hexadecimal format)"
address: String!
): SafeHoprAllowanceResult!
"""
Retrieve all safes
Returns all safe contracts indexed by the system.
Returns Error with code QUERY_FAILED if query fails.
"""
safes: SafesResult!
"""
Retrieve total aggregated wxHOPR balance across indexed safe contracts
Sums the wxHOPR token balances for safe contract addresses indexed by the system.
When ownerAddress is provided, restricts to safes whose registered accounts have that chain key.
Returns Error with code INVALID_ADDRESS if ownerAddress is malformed.
Returns Error with code QUERY_FAILED if query fails.
"""
safesBalance(
"Restrict to safes whose registered accounts have this chain key (hexadecimal format)"
ownerAddress: String
): SafesBalanceResult!
"""
Retrieve aggregated TicketRedeemed statistics filtered by safe and/or node address
At least one filter field must be provided: safeAddress, nodeAddress, or both.
If only safeAddress is provided, all rows for that safe are aggregated.
If only nodeAddress is provided, all rows for that node are aggregated.
If both are provided, the single matching safe/node pair row is returned.
If filters match no rows, zero totals are returned.
Returns Error with code MISSING_FILTER if no filter field is provided.
Returns Error with code INVALID_ADDRESS if any provided address format is invalid.
Returns Error with code QUERY_FAILED if query fails.
"""
ticketRedemptionStats(
"Filter specifying which safe/node combination to aggregate"
filter: RedeemedStatsFilter!
): RedeemedStatsResult!
"""
Retrieve transaction status by ID
Returns the current status of a previously submitted transaction.
Returns Error with code INVALID_TRANSACTION_ID if ID format is invalid.
Returns Error with code QUERY_FAILED if query fails.
Returns None if transaction ID is not found.
"""
transaction("Transaction ID to query (UUID)" id: ID!): TransactionResult
"""
Retrieve transaction count for any Ethereum address
This query returns the transaction count for any address type:
- For EOAs (Externally Owned Accounts): Returns the transaction count via eth_getTransactionCount
- For Safe contracts: Returns the Safe's internal nonce via nonce() function
- For other contracts: Attempts nonce() call, falls back to eth_getTransactionCount
The transaction count increments with each transaction sent or executed by the address.
Returns Error with code INVALID_ADDRESS if address format is invalid.
Returns Error with code QUERY_FAILED if blockchain query fails.
"""
transactionCount(
"Address to query (hexadecimal format) - supports EOAs and contracts"
address: String!
): TransactionCountResult!
"""
API version information
Returns the current version of the blokli-api package
"""
version: String!
}
"""
Outcome of a single ticket redemption attempt.
"""
enum RedemptionResult {
"Ticket was successfully redeemed on-chain."
REDEEMED
"Ticket redemption was rejected (inner Safe transaction failed)."
REJECTED
}
"""
Details of a ticket redemption event.
Uniquely identifies the ticket and reports whether it was accepted or rejected.
"""
type RedeemTicketDetails {
"Epoch of the channel where the ticket was redeemed"
epoch: UInt64!
"Index of the ticket within the channel epoch"
index: UInt64!
"Issuer account on-chain address in hexadecimal format"
issuerAddress: String!
"Recipient account on-chain address in hexadecimal format"
recipientAddress: String!
"Outcome of the redemption attempt"
result: RedemptionResult!
}
"""
Aggregated ticket redemption statistics, covering both successful redemptions and failed attempts.
"""
type RedeemedStats {
"Total amount from matching successful ticket redemption events"
redeemedAmount: TokenValueString!
"Total number of matching successful ticket redemption events"
redemptionCount: UInt64!
"Total amount from matching failed ticket redemption attempts"
rejectedAmount: TokenValueString!
"Total number of matching failed ticket redemption attempts"
rejectionCount: UInt64!
}
"""
Filter for ticket redemption stats queries.
At least one field must be provided. Providing both fields restricts the result
to the single matching safe/node pair; providing only one aggregates all rows
for that address.
"""
input RedeemedStatsFilter {
"Destination node address to filter by (hexadecimal format)"
nodeAddress: String
"Safe contract address to filter by (hexadecimal format)"
safeAddress: String
}
"""
Result type for redeemed statistics queries with filters
"""
union RedeemedStatsResult =
| RedeemedStats
| MissingFilterError
| InvalidAddressError
| QueryFailedError
"""
RPC or blockchain error during transaction submission
"""
type RpcError {
"Error code"
code: String!
"Human-readable error message"
message: String!
}
"""
HOPR Safe contract deployment information
"""
type Safe {
"Safe contract address (hexadecimal format)"
address: String!
"Legacy chain key field retained for backward compatibility"
chainKey: String!
@deprecated(
reason: "Use owners instead. chainKey is legacy Safe metadata and may not reflect the current owner set."
)
"HOPR Node Management Module address (hexadecimal format)"
moduleAddress: String!
"Current owner addresses reconstructed from indexed Safe events"
owners: [String!]!
"List of registered node addresses (hexadecimal format) for this Safe"
registeredNodes: [String!]!
"Current signer threshold reconstructed from indexed Safe events"
threshold: String
}
"""
Internal Safe contract execution result
"""
type SafeExecution {
"Revert reason if execution failed and reason is decodable (null if succeeded or reason unavailable)"
revertReason: String
"Safe internal transaction hash (bytes32 hex). Null for module-executed transactions (the standard HOPR path via execTransactionFromModule) since module events do not carry a txHash. For direct execTransaction calls, null only if event data was malformed."
safeTxHash: Hex32
"Whether the internal Safe transaction succeeded"
success: Boolean!
}
"""
Safe HOPR token allowance information for a specific Safe address
"""
type SafeHoprAllowance {
"Safe contract address"
address: String!
"WxHOPR token allowance granted by the safe to the channels contract"
allowance: TokenValueString!
}
"""
Result type for Safe HOPR allowance queries
"""
union SafeHoprAllowanceResult =
| SafeHoprAllowance
| InvalidAddressError
| QueryFailedError
"""
Result type for single safe queries
"""
union SafeResult = Safe | InvalidAddressError | QueryFailedError
"""
Result union for selector-based safe lookups that always return safe vectors on success.
"""
union SafeByResult = SafesList | InvalidAddressError | QueryFailedError
"""
Aggregated wxHOPR holdings across all indexed safe contracts
"""
type SafesBalance {
"Sum of wxHOPR balances for all safe contract addresses"
balance: TokenValueString!
"Number of safes included"
count: Int!
}
"""
Result type for total safe HOPR balance query
"""
union SafesBalanceResult = InvalidAddressError | QueryFailedError | SafesBalance
"""
Selector type for safe lookup queries.
"""
enum SafeSelectorInput {
"Filter by safe contract address"
ADDRESS
"Legacy alias for owner address filtering"
CHAIN_KEY
@deprecated(
reason: "Use OWNER instead. CHAIN_KEY is a legacy alias for Safe owner lookup."
)
"Filter by current safe owner address"
OWNER
"Filter by registered node address"
REGISTERED_NODE
}
"""
Success response for safes list query
"""
type SafesList {
"List of safes"
safes: [Safe!]!
}
"""
Result type for safes list query
"""
union SafesResult = SafesList | QueryFailedError
"""
Result type for asynchronous transaction submission
"""
union SendTransactionAsyncResult =
| Transaction
| ContractNotAllowedError
| FunctionNotAllowedError
| RpcError
"""
Result type for fire-and-forget transaction submission
"""
union SendTransactionResult =
| SendTransactionSuccess
| ContractNotAllowedError
| FunctionNotAllowedError
| RpcError
"""
Success response for fire-and-forget transaction submission
"""
type SendTransactionSuccess {
"Transaction hash after successful submission"
transactionHash: Hex32!
}
"""
Result type for synchronous transaction submission
"""
union SendTransactionSyncResult =
| Transaction
| ContractNotAllowedError
| FunctionNotAllowedError
| RpcError
| TimeoutError
"""
Root subscription type providing real-time updates via Server-Sent Events (SSE)
"""
type SubscriptionRoot {
"""
Subscribe to real-time updates of account information
Provides updates whenever there is a change in account information, including
balance changes, Safe address linking, and multiaddress announcements.
Optional filters can be applied to only receive updates for specific accounts.
"""
accountUpdated(
"Filter by chain key (hexadecimal format)"
chainKey: String
"Filter by account keyid"
keyid: Int
"Filter by packet key (peer ID format)"
packetKey: String
): Account!
"""
Subscribe to real-time updates of payment channels
Provides updates whenever there is a change in the state of any payment channel,
including channel opening, balance updates, status changes, and channel closure.
Optional filters can be applied to only receive updates for specific channels.
"""
channelUpdated(
"Filter by concrete channel ID (hexadecimal format)"
concreteChannelId: String
"Filter by destination node keyid"
destinationKeyId: Int
"Filter by source node keyid"
sourceKeyId: Int
"Filter by channel status"
status: ChannelStatus
): Channel!
"""
Subscribe to readiness-state updates for the API instance
Emits the current readiness state immediately after subscription, then streams
later state transitions.
"""
health: ReadinessState!
"""
Subscribe to real-time updates of key binding fee
Emits the current fee once on subscription, then streams updates whenever
the indexer processes a KeyBindingFeeUpdate event.
"""
keyBindingFeeUpdated: TokenValueString!
"""
Subscribe to the opened payment channels graph with real-time updates
**Streaming Behavior:**
- Emits one OpenedChannelsGraphEntry per open channel
- Each entry contains a single channel with its source and destination accounts
- On subscription start, emits all existing open channels as separate entries
- Subsequently, emits updates when any channel changes, including non-open states
**Building the Graph:**
Clients receive entries incrementally (one per channel) and should accumulate
them by channel.concreteChannelId to build the complete network topology.
CLOSED entries are intentional removal signals for consumers that maintain an
open-channel graph.
**Update Triggers:**
An entry is re-emitted for a channel when:
- The channel's status changes (e.g., OPEN → PENDINGTOCLOSE)
- The channel's balance changes
- The channel closes (emitted with CLOSED status so consumers can remove it)
- A new channel opens (new entry emitted)
**Example:**
If the network has three open channels: channelA (A→B), channelB (B→A), channelC (A→C),
the subscription emits three separate OpenedChannelsGraphEntry objects, each containing
one channel with its source and destination accounts.
**Note:** This is a directed graph. Bidirectional communication requires
channels in both directions, each emitted as a separate entry.
"""
openedChannelGraphUpdated: OpenedChannelsGraphEntry!
"""
Subscribe to newly deployed safes
Emits Safe deployment events in real-time as they are indexed.
"""
safeDeployed: Safe!
"""
Subscribe to real-time updates of ticket price and winning probability
Provides updates whenever there is a change in the ticket price or minimum
winning probability on-chain. These values are essential for ticket validation
and payment channel operation.
"""
ticketParametersUpdated: TicketParameters!
"""
Subscribe to real-time updates of ticket redemptions.
Streams a RedeemTicketDetails item each time a ticket redemption is observed
on-chain. Filters are optional and ANDed; omit all to receive every event.
"""
ticketRedeemed(
"Filter by channel ID (hexadecimal format)"
channelId: ID
"Filter by ticket issuer (hexadecimal format)"
issuerAddress: ID
"Filter by ticket recipient (hexadecimal format)"
recipientAddress: ID
): RedeemTicketDetails!
"""
Subscribe to real-time updates of a specific transaction
Provides updates whenever the status of the specified transaction changes,
including validation, submission, confirmation, revert, and failure events.
"""
transactionUpdated("Transaction ID to monitor (UUID)" id: ID!): Transaction!
}
"""
Ticket price and winning probability parameters
"""
type TicketParameters {
"Current minimum ticket winning probability (decimal value between 0.0 and 1.0)"
minTicketWinningProbability: Float!
"Current HOPR token price"
ticketPrice: TokenValueString!
}
"""
Operation timed out
"""
type TimeoutError {
"Error code"
code: String!
"Human-readable error message"
message: String!
}
"""Token type for balance queries"""
enum Token {
"wxHOPR wrapped HOPR token"
HOPR
"Native token (xDAI)"
NATIVE
"xHOPR native HOPR token"
XHOPR
}
"""
Human-readable token representation.
Format: value [wei] token
Examples:
10 wei wxHOPR
10 wxHOPR
10.1 wxHOPR
.1 wxHOPR
"""
scalar TokenValueString
"""
Transaction submission result
"""
type Transaction {
"Unique identifier for the transaction (UUID)"
id: ID!
"Internal Safe execution result (null for non-Safe transactions or before confirmation)"
safeExecution: SafeExecution
"Current status of the transaction"
status: TransactionStatus!
"Timestamp when transaction was submitted"
submittedAt: DateTime!
"Transaction hash from successful blockchain submission"
transactionHash: Hex32!
}
"""
Transaction count information for any Ethereum address
"""
type TransactionCount {
"Address queried (hexadecimal format)"
address: String!
"Current transaction count or nonce for the address"
count: UInt64!
}
"""
Result type for transaction count queries
"""
union TransactionCountResult =
| TransactionCount
| InvalidAddressError
| QueryFailedError
"""
Input for transaction submission
"""
input TransactionInput {
"Raw signed transaction data in hexadecimal format (with or without 0x prefix)"
rawTransaction: String!
}
"""
Result type for transaction operations
"""
union TransactionResult = Transaction | InvalidTransactionIdError
"""
Status of a submitted transaction
"""
enum TransactionStatus {
"Transaction has been confirmed on-chain with success"
CONFIRMED
"Transactions are never emitted in this state; they go directly to SUBMITTED"
PENDING
@deprecated(
reason: "Transactions go directly to SUBMITTED. This variant exists only for backwards compatibility and will be removed in a future release."
)
"Transaction was included on-chain but reverted (receipt.status = 0)"
REVERTED
"Transaction submission failed"
SUBMISSION_FAILED
"Transaction has been submitted and is awaiting confirmation"
SUBMITTED
"Transaction was not mined within timeout window"
TIMEOUT
"Transaction validation failed"
VALIDATION_FAILED
}
"""
Unsigned 64-bit integer represented as a string to avoid JavaScript precision loss.
Used for values that exceed the 32-bit signed integer range of GraphQL Int.
Maximum value: 18446744073709551615
"""
scalar UInt64