DOCUMENTATION

Introduction

Hallmark is a decentralized read-RPC and block explorer for Solana. Every answer ships with a signed receipt you can verify offline — proof-of-serve, not trust.

Developers send read requests to https://hallmarkgrid.xyz/api/v1. A node reads chain state, stamps the observed slot, signs an ed25519 receipt over a canonical digest, and returns { result, slot, receipt }. Over 90% of RPC traffic is reads; Hallmark specializes the read path so it stays fast, cheap, and verifiable.

The free tier is open — no login, IP-rate-limited. Hit it with curl:

curl https://hallmarkgrid.xyz/api/v1/balance/So11111111111111111111111111111111111111112

{
  "result": { "lamports": 1561567620032, "sol": 1561.56 },
  "slot": 430335835,
  "receipt": {
    "query": "getBalance:So111…1112",
    "answerDigest": "aaebfa99…5518",
    "slot": 430335835,
    "issuedAt": 1783006459218,
    "sig": "24b3e377…b69a05"
  }
}

Or with the SDK — one call reads, one call proves it:

import { HallmarkClient } from "hallmark-sdk";

const hallmark = new HallmarkClient();

const { result, receipt } = await hallmark.getBalance(addr);
await hallmark.verify(receipt); // → true

Anonymous requests work out of the box and are rate-limited by IP. To lift limits and get per-key analytics, pass an API key in the X-Api-Key header. Holding $HALLMARK raises your tier further.

curl https://hallmarkgrid.xyz/api/v1/slot \
  -H "X-Api-Key: hallmark_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Every endpoint returns the same envelope: { result, slot, receipt }. All responses are no-store — reads are never cached, freshness is the point.

Get Balance

GET /api/v1/balance/:address — lamport + SOL balance.

GET https://hallmarkgrid.xyz/api/v1/balance/:address
→ { result: { lamports, sol }, slot, receipt }

Get Account Info

GET /api/v1/account/:address — owner, lamports, executable flag, data length.

GET https://hallmarkgrid.xyz/api/v1/account/:address
→ { result: { owner, lamports, executable, rentEpoch, dataLen }, slot, receipt }

Get Slot

GET /api/v1/slot — the current processed slot.

GET https://hallmarkgrid.xyz/api/v1/slot
→ { result: { slot }, slot, receipt }

Token Accounts By Owner

GET /api/v1/token/accounts-by-owner?owner=:address — every SPL token account a wallet owns, with mint and amount.

GET https://hallmarkgrid.xyz/api/v1/token/accounts-by-owner?owner=:address
→ { result: { count, accounts: [{ account, mint, amount, decimals }] }, slot, receipt }

Realtime Stats

GET /api/v1/stats — live slot, TPS, epoch, and epoch progress. Unsigned; used for dashboards and the live strip.

A receipt is an ed25519 signature over a deterministic, key-sorted encoding of { query, result, slot, issuedAt }. To verify, recompute the SHA-256 digest of those exact bytes and check the signature against the published key at https://hallmarkgrid.xyz/api/v1/pubkey. No network round-trip, no trust in the responder.

import { verifyReceipt } from "hallmark-sdk";

const { ok, digestMatches, signatureValid } =
  await verifyReceipt(PUBLIC_KEY, signedResponse);
// ok === digestMatches && signatureValid

Tamper with the result or swap the key and verification fails. Two deeper guarantees layer on top: account-hash proofs bind answers to a hash of the underlying account state at a slot, and known-answer audits probe nodes with queries whose truth is already known.

hallmark-sdk is a thin, typed, receipt-aware client. Every method returns { result, slot, receipt } and verify() runs the same check in the browser or on a server.

npm install hallmark-sdk

import { HallmarkClient } from "hallmark-sdk";

const hallmark = new HallmarkClient({
  baseUrl: "https://hallmarkgrid.xyz",   // optional; defaults to same origin
  apiKey,               // optional; free tier works without
});

const bal   = await hallmark.getBalance(addr);
const acct  = await hallmark.getAccountInfo(addr);
const slot  = await hallmark.getSlot();
const toks  = await hallmark.getTokenAccountsByOwner(owner);

await hallmark.verify(bal); // → { ok: true, ... }