Documentation

SUM Chain JSON-RPC API

SUM Chain exposes a JSON-RPC 2.0 API for chain queries, transaction submission, and integration with the storage protocol, NFTs, tokens, encrypted messaging, policy accounts, and document-credential layers. The native currency is Koppa (Ϙ) with 9 decimal places.

All 143 methods on this page are verified against the live mainnet RPC.

Connection

Public mainnet endpoint:

https://rpc.sumchain.io

Every request follows JSON-RPC 2.0. The Content-Type: application/json header is required.

curl -X POST https://rpc.sumchain.io \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain_id","params":[],"id":1}'

Currency & Units

NameSymbolDecimalsBase Unit
KoppaϘ91 Ϙ = 1,000,000,000

All amounts in the API are represented in base units. Examples: 1000000000 = 1 Ϙ, 1000000 = 0.001 Ϙ (typical fee).

Addresses

Addresses are 20 bytes derived from an Ed25519 public key: Address = Blake3(pubkey)[12..32].

Two display formats are accepted in API parameters:

  • Base58 with checksum (default Display): e.g. 8zZ1pfbpUcAmoByWKYgJgiFZWpmhWQKJ4
  • Hex: e.g. 0x1a2b3c4d...

Method Index

Chain
11 methods
Account
11 methods
Transactions
9 methods
Decentralized Storage (PoR)
4 methods
Validators & Consensus
25 methods
NFTs (SUM-721)
7 methods
Fungible Tokens (SRC-20)
6 methods
Smart Contracts (WASM)
7 methods
Encrypted Messaging (SRC-201)
16 methods
Document Credentials (SRC-80X)
16 methods
Employment Credentials (SRC-88X)
16 methods
Policy Accounts (Multi-Sig)
10 methods
Node & Network
5 methods

Chain

Block and chain metadata.

chain_id

Returns the chain identifier.

Request
{"jsonrpc":"2.0","method":"chain_id","params":[],"id":1}
Response (live)
{"jsonrpc":"2.0","result":1,"id":1}
get_latest_block

Returns the most recent block.

Request
{"jsonrpc":"2.0","method":"get_latest_block","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x69226247daff051c87d610b0a5df1f793cd9b7cfa2d4bd70cb26166d541a0c64",
    "height": 4807038,
    "parent_hash": "0xec94cb97f6f97b4e78ad2054718fde0d0a30bea6a78ac1b69cb34c191df6c422",
    "timestamp": 1777137175565,
    "tx_root": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "state_root": "0xb9e67e5c251da9131a183a1658c5925690c6752a29c4a1c9e22c91b91e2f34b9",
    "proposer": "e64e11c6f9f9937a1bc6a4535701f036388451e6cc83ad9f25b143973d90a4cd",
    "tx_count": 0,
    "transactions": []
  },
  "id": 1
}
get_block_by_height

Returns the block at a given height.

Request
{"jsonrpc":"2.0","method":"get_block_by_height","params":[4807000],"id":1}
get_block_by_hash

Returns the block matching a hex hash.

get_blocks

Paginated block listing.

get_finality

Returns finalized height + the depth-based finality config (default 6 blocks).

Request
{"jsonrpc":"2.0","method":"get_finality","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "finalized_height": 4807033,
    "finalized_hash": "0x606ec3b283fe3eed4cdd4ca1cc5c5c5a262dbbb4ee10ebe4dba12dc22aec955a",
    "current_height": 4807039,
    "finality_depth": 6,
    "pending_finality": 6
  },
  "id": 1
}
is_block_finalized

Reports whether a given height is finalized.

eth_blockNumber

Latest block number in hex (Ethereum-compatible).

Request
{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}
Response (live)
{"jsonrpc":"2.0","result":"0x49597f","id":1}
sum_blockNumber

Same as eth_blockNumber, sum_-prefixed alias.

sum_getLatestBlock

Alias of get_latest_block.

sum_getBlockByHeight

Alias of get_block_by_height.

Account

Balance, nonce, and account state. Addresses accept Base58 (with checksum) or 0x-prefixed hex.

get_balance

Returns balance in base units (1 Koppa = 1,000,000,000 base units).

Request
{"jsonrpc":"2.0","method":"get_balance","params":["8zZ1pfbpUcAmoByWKYgJgiFZWpmhWQKJ4"],"id":1}
Response (live)
{"jsonrpc":"2.0","result":"500000001018000000","id":1}
get_nonce

Returns the next expected nonce for the account.

get_account

Returns balance + nonce in one call.

account_getPublicKey

Returns the registered Ed25519 public key for an address. Required for encrypted messaging recipients.

eth_getBalance

Hex-formatted balance (Ethereum-compatible). Optional second `block` argument.

sum_getBalance

sum_-prefixed alias of get_balance.

sum_getNonce

sum_-prefixed alias of get_nonce.

sum_getTransactionCount

Total transactions sent by an address.

sum_getTransactionsByAddress

Tx history (sender + recipient) for an address.

sum_getTransactionsBySender

Tx history (sender only).

sum_getTransactionsByRecipient

Tx history (recipient only).

Transactions

Submit, look up, and inspect transactions.

send_raw_transaction

Submits a hex-encoded signed transaction. Returns the tx hash.

Request
{"jsonrpc":"2.0","method":"send_raw_transaction","params":["0xabc..."],"id":1}
Response (live)
{"jsonrpc":"2.0","result":{"tx_hash":"0xdef..."},"id":1}
get_transaction

Returns a transaction by hash.

get_receipt

Returns receipt (success/failure + gas) by tx hash.

get_pending_transactions

Lists pending mempool transactions.

pending_tx_count

Mempool size.

Request
{"jsonrpc":"2.0","method":"pending_tx_count","params":[],"id":1}
Response (live)
{"jsonrpc":"2.0","result":0,"id":1}
sum_sendRawTransaction

sum_-prefixed alias of send_raw_transaction.

sum_getTransaction

sum_-prefixed alias.

sum_getReceipt

sum_-prefixed alias.

sum_getPendingTransactions

sum_-prefixed alias.

Decentralized Storage (PoR)

Native L1 Proof-of-Retrievability — query files, challenges, and archive nodes. Powers snip.sumchain.io and the storage marketplace.

storage_getFundedFiles

Returns all files with fee_pool > 0. New archive nodes use this to discover what to store and earn from.

Request
{"jsonrpc":"2.0","method":"storage_getFundedFiles","params":[],"id":1}
Response (live)
{"jsonrpc":"2.0","result":[],"id":1}
storage_getAccessList

Returns full metadata for a file by its merkle_root, including the on-chain ACL.

Request
{"jsonrpc":"2.0","method":"storage_getAccessList","params":["0xabc..."],"id":1}
storage_getActiveChallenges

Open Proof-of-Retrievability challenges assigned to a specific archive node. Failure to respond within 50 blocks slashes 5% of stake.

Request
{"jsonrpc":"2.0","method":"storage_getActiveChallenges","params":["8zZ1pfbpUcAmoByWKYgJgiFZWpmhWQKJ4"],"id":1}
storage_getNodeRecord

Returns the NodeRegistry record (role, staked balance, status) for an address.

Validators & Consensus

Active set, staking, delegation, slashing, and epoch info.

get_validators

Active validator set with current proposer.

Request
{"jsonrpc":"2.0","method":"get_validators","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "public_key": "GW1pJKzqDmmHczMGz5g7CV51RgDuR6kKw76yZ1cVbEv8",
        "address": "8zZ1pfbpUcAmoByWKYgJgiFZWpmhWQKJ4",
        "is_current_proposer": true
      },
      {
        "public_key": "7jUZxm5rJ5PazGYkrtJ4sUJj7ztib2VHEoM2Yc4Liydy",
        "address": "D7Ls8H7Y2jCqYEEUUxWUcgQkF9cKhHxjV",
        "is_current_proposer": false
      }
    ]
  },
  "id": 1
}
sum_getValidators

sum_-prefixed alias.

staking_getValidator

Validator by pubkey.

staking_getValidatorByAddress

Validator by address.

staking_getValidators

All validators.

staking_getActiveValidators

Active set only.

staking_getSummary

Aggregate stats.

staking_getParams

Staking parameters.

staking_getTotalStake

Sum of all stake.

delegation_getDelegation

Single delegation lookup.

delegation_getDelegationsByDelegator

Delegations made by an address.

delegation_getDelegationsByValidator

Delegations to a validator.

delegation_getDelegatorSummary

Aggregate per delegator.

delegation_getUnbondingDelegations

Pending unbondings.

delegation_getValidatorDelegationSummary

Aggregate per validator.

slashing_getRecords

Historical slashing records.

slashing_getRecentRecords

Recent records.

slashing_getSigningInfo

Per-validator missed-block tracking.

slashing_getAllSigningInfo

All validators.

slashing_getSummary

Aggregate stats.

slashing_isTombstoned

Permanent-jail check.

epoch_getInfo

Current epoch metadata.

Request
{"jsonrpc":"2.0","method":"epoch_getInfo","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "current_epoch": 333,
    "current_height": 4807057,
    "epoch_length": 14400,
    "epoch_start_height": 4795200,
    "epoch_end_height": 4809599,
    "blocks_remaining": 2542,
    "stake_weighted_selection": true
  },
  "id": 1
}
validatorSet_getCurrent

Active validator set.

validatorSet_getByEpoch

Set for a specific epoch.

validatorSet_getProposer

Proposer at a given height.

NFTs (SUM-721)

Native NFT standard.

nft_getCollection

Collection metadata.

nft_getToken

Single token.

nft_getTokensByOwner

Tokens owned by an address.

nft_getTokensInCollection

Tokens in a collection.

nft_balanceOf

Number of tokens an address holds.

nft_ownerOf

Owner of a specific token.

nft_tokenExists

Existence check.

Fungible Tokens (SRC-20)

Native fungible-token standard, ERC-20 compatible interface.

token_getToken

Token metadata.

token_balanceOf

Holder balance for a token.

token_getTokensByOwner

Tokens an address holds.

token_allowance

ERC-20-style allowance lookup.

token_totalSupply

Total supply of a token.

token_exists

Existence check.

Smart Contracts (WASM)

sumc-runtime WASM contract calls.

contract_getContract

Contract metadata.

contract_isContract

Existence check.

contract_call

Read-only view call.

contract_estimateGas

Gas estimation.

contract_getCodeHash

Code-hash lookup.

contract_getStorageAt

Raw storage slot read.

contract_getBalance

Contract balance.

Encrypted Messaging (SRC-201)

On-chain encrypted messaging using X25519 + XChaCha20-Poly1305.

messaging_getConfig

Per-chain messaging parameters.

Request
{"jsonrpc":"2.0","method":"messaging_getConfig","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "daily_quota": 100,
    "max_message_size": 65535,
    "min_trust_stake": "100000000000",
    "sponsorship_enabled": true
  },
  "id": 1
}
messaging_registerSponsored

Registers a public key for an address (sponsored — fee paid by relayer). Required before receiving messages. Not idempotent: a duplicate call returns success: false with "Public key already registered" — check via account_getPublicKey first.

messaging_submitSponsored

Submits an encrypted message via a sponsoring relayer.

messaging_getQuota

Quota status for a sender.

messaging_getInboxFilter

Recipient inbox-filter rules.

messaging_getMessages

Inbox query.

messaging_getSentMessages

Outbox query.

messaging_getMessageByTxHash

Message lookup by tx.

messaging_getMessagesInBlock

Messages in a block.

messaging_getMessageData

Message ciphertext.

messaging_getPendingPayment

Pending sponsorship payment.

messaging_getPendingPayments

All pending payments.

messaging_getTrustStake

Trust-stake balance.

messaging_getSpamScore

Spam-score lookup.

messaging_isContact

Contact-list check.

messaging_isBlocked

Block-list check.

Document Credentials (SRC-80X)

Verifiable identity, credentials, and academic-credential issuance.

docclass_getConfig

Config & parameters.

docclass_getSummary

Aggregate stats.

docclass_getIdentity

Identity by id.

docclass_getIdentityByController

Identity by controlling address.

docclass_canIssue

Authorization check for an issuer.

docclass_getCredential

Credential by id.

docclass_isCredentialValid

Validity + revocation check.

docclass_getCredentialsBySubject

All credentials for a subject.

docclass_getCredentialsByIssuer

All credentials from an issuer.

docclass_getIssuer

Issuer record.

docclass_getIssuers

All registered issuers.

docclass_getIssuersByJurisdiction

Issuers by jurisdiction code.

docclass_getAcademicCredentialsByHolder

Academic credentials for a holder.

docclass_registerAcademicIssuer

Register an academic issuer (write).

docclass_issueAcademicCredential

Issue an academic credential (write).

docclass_revokeAcademicCredential

Revoke an academic credential (write).

Employment Credentials (SRC-88X)

On-chain employment & income attestations.

employment_listIssuers

All registered employment issuers.

employment_getIssuer

Issuer record.

employment_registerIssuer

Register an employer issuer (write).

employment_getSummary

Aggregate stats.

employment_getCredential

Credential by id.

employment_getCredentialsByEmployee

All credentials for an employee.

employment_getCredentialsByEmployeeAddress

By employee address.

employment_getCredentialsByEmployer

By employer.

employment_getActiveCredentialsByEmployee

Active only.

employment_getActiveCredentialsByEmployeeAddress

Active only by address.

employment_createCredential

Issue a new employment credential (write).

employment_revokeCredential

Revoke a credential (write).

employment_verifyEmployment

Verify employment claim.

employment_getIncomeAttestation

Income attestation by id.

employment_getIncomeAttestationsBySubject

By subject.

employment_getIncomeAttestationsByHolderAddress

By holder address.

Policy Accounts (Multi-Sig)

Consensus-level multi-sig group governance — accounts, proposals, execution.

policy_createAccount

Create a new policy account (write).

policy_getAccount

Account by id.

policy_getAccountByAddress

Account by address.

policy_listMemberAccounts

Accounts where address is a member.

policy_submitProposal

Submit a new proposal (write).

policy_executeProposal

Execute an approved proposal (write).

policy_cancelProposal

Cancel a pending proposal (write).

policy_getProposal

Proposal by id.

policy_listProposals

All proposals for an account.

policy_listPendingProposals

Pending only.

Node & Network

Operator-facing endpoints for monitoring.

health

Liveness probe.

Request
{"jsonrpc":"2.0","method":"health","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "status": "ok",
    "chain_id": 1,
    "height": 4807039,
    "peer_count": 2,
    "is_validator": true,
    "is_synced": true
  },
  "id": 1
}
node_info

Version, peer ID, uptime.

Request
{"jsonrpc":"2.0","method":"node_info","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "version": "0.1.0",
    "chain_id": 1,
    "network": "sumchain-1",
    "peer_id": "12D3KooWJdKDCZn9Wu5mo1WBMLRwEeej9abjTLDvgZRzLwZv6kdW",
    "is_validator": true,
    "current_height": 4807038,
    "peer_count": 2,
    "mempool_size": 0,
    "uptime_seconds": 238205
  },
  "id": 1
}
get_metrics

Prometheus-style metrics snapshot.

get_peers

Connected peers.

get_p2p_stats

libp2p connection statistics.

Request
{"jsonrpc":"2.0","method":"get_p2p_stats","params":[],"id":1}
Response (live)
{
  "jsonrpc": "2.0",
  "result": {
    "total_known_peers": 2,
    "connected_peers": 2,
    "inbound_connections": 0,
    "outbound_connections": 2,
    "banned_peers": 0,
    "max_connections": 100,
    "max_inbound": 50,
    "max_outbound": 50
  },
  "id": 1
}

All 143 endpoints listed above are verified against https://rpc.sumchain.io.

← Back to Get Started