RPC

Proxy

POST a single JSON-RPC object to /rpc/v1/{network}. Supported networks: finney (mainnet) and test (testnet). WebSocket upgrade is not available on this HTTP path — use wss.metagraph.sh or a public WSS endpoint.

POST https://api.metagraph.sh/rpc/v1/{network}

• finney → https://api.metagraph.sh/rpc/v1/finney
• test → https://api.metagraph.sh/rpc/v1/test

curl -s 'https://api.metagraph.sh/rpc/v1/finney' \
  -X POST -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}'

Catalog & analytics

Static registry projections and live proxy telemetry. Live explorer UI for pools and traffic lives on Endpoints.

Allowlisted methods

Only safe read methods pass. Mutating and heavy prefixes are denied. State-query methods need param validation and a separate rate budget.

Safe methods

chain_getBlock · chain_getBlockHash · chain_getFinalizedHead · chain_getHeader · rpc_methods · state_getRuntimeVersion · system_chain · system_health · system_name · system_properties · system_version

State-query (extra rate budget)

state_getStorage · state_getKeysPaged

Denied prefixes

author_* · state_call* · sudo_* · payment_* · contracts_*

Gated fullnode access

An account-gated tier for real fullnode RPC access — not just the read-only proxy above. Requires a wallet-signed login; no invite code, self-serve. Grants the same safe read methods as the public proxy, plus author_submitExtrinsic (real transaction broadcast), at a materially higher rate limit than the keyless tier. Every key starts on the default (free) tier; a higher tier is granted directly to your account, not by a code you present.

1. Request a challenge

curl -s https://api.metagraph.sh/api/v1/auth/wallet/challenge \
  -X POST -H 'content-type: application/json' \
  -d '{"ss58":"YOUR_SS58_ADDRESS"}'

Returns a message to sign and how long it stays valid.

2. Sign the message with your wallet

Sign the returned message as raw bytes with your own wallet signer (e.g. @polkadot/extension-dapp's signRaw({ address, data: message, type: "bytes" })). The signing key material never reaches this API — only the resulting signature does.

3. Verify and get a session

curl -s https://api.metagraph.sh/api/v1/auth/wallet/verify \
  -X POST -H 'content-type: application/json' \
  -d '{"ss58":"YOUR_SS58_ADDRESS","signature":"YOUR_HEX_SIGNATURE"}'

Returns a session_token — scoped only to key management (create/list/revoke your own keys), not itself the RPC credential.

4. Mint your key

curl -s https://api.metagraph.sh/api/v1/keys \
  -X POST \
  -H "authorization: Bearer YOUR_SESSION_TOKEN"

Returns the full mg_... key exactly once — store it yourself; it's never shown again, along with a key_id. Revoke anytime with DELETE /api/v1/keys/{key_id}, presenting the same session.

5. Call the gated proxy

curl -s 'https://api.metagraph.sh/rpc/v1/fullnode?authorization=YOUR_KEY' \
  -X POST -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}'

The key travels as an ?authorization= query parameter, not a header — matching the convention several hosted-RPC providers already use, so existing WSS-shaped client code needs minimal changes to point here.

Limits

Hard caps on every proxied POST. Matching constants live in workers/config.mjs and workers/request-handlers/rpc-proxy.mjs.