API Reference

The Gridcoin Blockchain Stamping API is a public, read-mostly HTTP service that lets you create SHA-256 stamps on the Gridcoin blockchain, look up existing stamps, and inspect the service wallet. Responses follow the JSON:API specification.

• Base URL

  https://stamp.gridcoin.club/api

• Content-Type

  application/vnd.api+json

• Authentication

  None. All endpoints are public by design.

• CORS

  Open to all origins. Safe to call directly from the browser.

The fastest way to confirm the service is reachable is a GET /api/status call:

curl https://stamp.gridcoin.club/api/status

{
  "data": {
    "type": "status",
    "attributes": {
      "name": "grc-stamp",
      "version": "1.2.1",
      "maintenance": false
    }
  }
}

A note on curl and JSON:API brackets

JSON:API query parameters use literal square brackets — for example page[size]=10 or filter[block][gt]=0. By default curl interprets […] in a URL as a URL globbing range and fails with bad range in URL position …. Every example on this page uses the -g (also spelled --globoff) flag to disable that behaviour. If you prefer, you can also URL-encode the brackets as %5B and %5D, or use the -G --data-urlencode form — whichever is the most convenient inside your tooling.

Collection endpoints support the standard JSON:API query parameters for pagination, sorting, sparse fieldsets, and filtering. Every parameter is optional; omitting all of them returns the first page of results in default order.

Pagination

• page[size] — items per page

  Default 25, maximum 100. Values above 100 are silently capped. A value of 0 falls back to the default of 25.

• page[number] — zero-indexed page number

  Offset is computed as page[number] × page[size]. Mutually exclusive with page[offset].

• page[offset] — absolute record offset

  Skip N records before returning results.

Every list response includes a top-level meta.count field with the total number of records matching the query.

Sorting

Pass sort=field for ascending order or sort=-field for descending. Multiple fields can be comma-separated (e.g. sort=-block,-id). Unspecified sort falls back to ascending id.

Sparse Fieldsets

Restrict the returned attributes with fields[stamps]=id,hash,block to reduce payload size. Keep id in the list — JSON:API requires it on every resource object.

Filtering

Simple exact-match filtering works on any field with filter[field]=value. Comparison operators are available via filter[field][op]=value. Supported operators: eq, ne, gt, gte, lt, lte.

Example

Fetch the 10 most recent confirmed stamps, returning only id, hash, block, and time:

curl -G 'https://stamp.gridcoin.club/api/stamps' \
  --data-urlencode 'page[size]=10' \
  --data-urlencode 'sort=-block' \
  --data-urlencode 'fields[stamps]=id,hash,block,time' \
  --data-urlencode 'filter[block][gt]=0'

All error responses follow the JSON:API error format: a top-level errors array containing one or more objects with a numeric status, a human-readable title, and an optional detail.

{
  "errors": [
    {
      "status": 400,
      "title": "\"hash\" length must be at least 64 characters long"
    }
  ]
}

You can reliably trigger this shape by posting an invalid hash:

curl -X POST 'https://stamp.gridcoin.club/api/stamps' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{"data":{"type":"stamps","attributes":{"hash":"not-a-hash"}}}'

Common status codes

• 400 Bad Request

  Request body or query string failed validation (wrong hash length, unsupported hashType, malformed JSON:API envelope).

• 404 Not Found

  No stamp with the requested id or hash.

• 406 Not Acceptable

  The service wallet does not hold enough GRC to create a new stamp. Try again later.

• 500 Internal Server Error

  Database, Redis, or Gridcoin RPC failure. Usually transient — retry after a short delay.

About the 406: the service wallet is currently shared across every caller of this public instance, and the operator tops it up as needed. If you hit a 406 and don't want to wait, you can keep the queue moving by sending a small amount of GRC to the wallet address returned by GET /api/wallet. Any GRC you contribute funds stamps for everyone, including you — there is no per-sender accounting.

Returns the service name, version, and whether the stamping service is currently in maintenance mode. A cheap call — use it for health checks.

curl https://stamp.gridcoin.club/api/status

{
  "data": {
    "type": "status",
    "attributes": {
      "name": "grc-stamp",
      "version": "1.2.1",
      "maintenance": false
    }
  }
}

The status resource has no id — it represents the service as a whole.

When maintenance is true, new stamps cannot be created; read endpoints remain available.

A stamp is a SHA-256 hash that has been (or is about to be) embedded in a Gridcoin transaction via OP_RETURN. Once the transaction is confirmed, the stamp becomes a permanent, publicly verifiable proof that the hash existed at a specific block height.

List stamps

Returns a JSON:API collection. Supports all conventions described in the JSON:API Conventions section.

curl -g 'https://stamp.gridcoin.club/api/stamps?page[size]=2&sort=-id'

{
  "meta": { "count": 2379 },
  "data": [
    {
      "id": "2379",
      "type": "stamps",
      "attributes": {
        "protocol": "0.0.1",
        "type": "sha256",
        "hash": "c8a6a89efcea21b1c3b9181110053694cd8fc204ca37a03e5f304b533ee659a6",
        "block": 3940142,
        "tx": "56886c5134ace2589d8cd0d49a61c8b6f6ca9e7135636bf76956537a9602a222",
        "rawTransaction": "6a265ea1ed000001c8a6a89efcea21b1c3b9181110053694cd8fc204ca37a03e5f304b533ee659a6",
        "time": 1775877184,
        "createdAt": "2026-04-11T03:12:06.000Z",
        "updatedAt": "2026-04-11T03:13:59.000Z"
      },
      "links": { "self": "/stamps/2379" }
    },
    {
      "id": "2378",
      "type": "stamps",
      "attributes": {
        "protocol": "0.0.1",
        "type": "sha256",
        "hash": "d1aa7e3b2caf3e6b7b25d0e8f02d1190178e466f78894cda55126e1928ecf0ae",
        "block": 3939884,
        "tx": "f26a9b4c5ec18401fa607820c4edfc21553173129cfa8ba16d6dec101f7792c7",
        "rawTransaction": "6a265ea1ed000001d1aa7e3b2caf3e6b7b25d0e8f02d1190178e466f78894cda55126e1928ecf0ae",
        "time": 1775855712,
        "createdAt": "2026-04-10T21:09:32.000Z",
        "updatedAt": "2026-04-10T21:16:02.000Z"
      },
      "links": { "self": "/stamps/2378" }
    }
  ]
}

Get a stamp by ID

The id is the internal auto-incrementing identifier returned by the list endpoint or by POST /api/stamps. To look up by hash instead, use /api/hashes/:hash.

curl https://stamp.gridcoin.club/api/stamps/3

{
  "data": {
    "id": "3",
    "type": "stamps",
    "attributes": {
      "protocol": "0.0.1",
      "type": "sha256",
      "hash": "5f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "block": 2394434,
      "tx": "a9a30f84d23a98b7d90c4581bbe94bbbfc40e05167656e2fe16c8deda5fa08ce",
      "rawTransaction": "6a265ea1ed0000015f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "time": 1634822384,
      "createdAt": "2021-10-21T13:18:45.000Z",
      "updatedAt": "2021-10-21T13:19:52.000Z"
    },
    "links": { "self": "/stamps/3" }
  }
}

A stamp that has not yet been mined into a block returns null for block, tx, rawTransaction, and time. Unknown ids return 404 Not Found with the standard error envelope.

Create a stamp

Submit a SHA-256 hash to be queued for stamping. The server batches queued hashes and embeds up to two at a time in a single OP_RETURN transaction, which is broadcast to the Gridcoin network.

Request body

• data.attributes.hash — required

  Exactly 64 hex characters matching /^[a-fA-F0-9]{64}$/ — lower- or upper-case both work. The SHA-256 digest of the document you want to stamp.

• data.attributes.hashType — optional

  Only "sha256" is currently accepted. Defaults to "sha256".

• data.attributes.protocol — optional

  Stamping protocol version. Only "0.0.1" is currently accepted. Defaults to "0.0.1".

curl -X POST 'https://stamp.gridcoin.club/api/stamps' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "stamps",
      "attributes": {
        "hash": "5f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503"
      }
    }
  }'

{
  "data": {
    "id": "3",
    "type": "stamps",
    "attributes": {
      "protocol": "0.0.1",
      "type": "sha256",
      "hash": "5f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "block": 2394434,
      "tx": "a9a30f84d23a98b7d90c4581bbe94bbbfc40e05167656e2fe16c8deda5fa08ce",
      "rawTransaction": "6a265ea1ed0000015f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "time": 1634822384,
      "createdAt": "2021-10-21T13:18:45.000Z",
      "updatedAt": "2021-10-21T13:19:52.000Z"
    },
    "links": { "self": "/stamps/3" }
  }
}

For a brand-new hash the response is the same shape with block, tx, rawTransaction, and time set to null until the scraper confirms the transaction on-chain.

Status codes

• 201 Created

  A new stamp was queued. The attributes for block / tx / rawTransaction / time are null until the transaction is mined.

• 200 OK

  The hash was already stamped. The existing record is returned instead of creating a duplicate.

• 400 Bad Request

  Validation failed — most commonly an incorrect hash length or an unsupported hashType.

• 406 Not Acceptable

  The service wallet is below the minimum balance and cannot broadcast new stamping transactions.

Look up a stamp by its SHA-256 hash instead of its internal id. If the same hash has been stamped more than once (for example, by different callers), the endpoint returns the earliest record — the one with the smallest time.

curl https://stamp.gridcoin.club/api/hashes/5f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503

{
  "data": {
    "id": "3",
    "type": "stamps",
    "attributes": {
      "protocol": "0.0.1",
      "type": "sha256",
      "hash": "5f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "block": 2394434,
      "tx": "a9a30f84d23a98b7d90c4581bbe94bbbfc40e05167656e2fe16c8deda5fa08ce",
      "rawTransaction": "6a265ea1ed0000015f334f14161952476adde3fbd843f93f647d47a0d7e30eb5d1635fb7569a2503",
      "time": 1634822384,
      "createdAt": "2021-10-21T13:18:45.000Z",
      "updatedAt": "2021-10-21T13:19:52.000Z"
    },
    "links": { "self": "/stamps/3" }
  }
}

Returns 404 Not Found if the hash has never been stamped by this service. The lookup is case-insensitive — upper- and lower-case hex both resolve to the same record.

The service wallet is a dedicated Gridcoin address that holds the GRC used to pay transaction fees when stamping. These endpoints are useful for monitoring dashboards, funding alerts, and confirming that the scraper is keeping up with the blockchain.

Wallet info

curl https://stamp.gridcoin.club/api/wallet

{
  "data": {
    "id": "S16teVjxKNaptDLFnPwxkjQE3aiHRcgpr5",
    "type": "wallet",
    "attributes": {
      "address": "S16teVjxKNaptDLFnPwxkjQE3aiHRcgpr5",
      "balance": 3001.73952722,
      "block": 3940586
    },
    "links": { "self": "/wallet/" }
  }
}

The id on a wallet resource is the Gridcoin address itself (the same value as attributes.address). balance is returned as a JSON number and block is the last Gridcoin block the scraper has processed.

Balance only

curl https://stamp.gridcoin.club/api/wallet/balance

{
  "data": {
    "type": "balance",
    "attributes": {
      "balance": 3001.73952722
    },
    "links": { "self": "/wallet/balance" }
  }
}

The balance resource has no id — it represents the current balance value, not an addressable record.