This API is responsible for managing keys and counts for all snapshot APIs
| Tier | Id | Max Requests (hub) | Max Requests (score-api) |
|---|---|---|---|
| Free | 0 | 200k | 200k |
| Pro | 1 | 5M | 2M |
| Extra | 2 | 4M | 2M |
New keys created via the whitelist method default to the Free tier (id 0).
Make sure to update limits in src/config.json
This API depends on a couple of services:
- Node.js (>= v22.6.0)
- PostgreSQL (v18 — older versions likely work but are untested)
You can use the docker-compose service to start one up quickly with:
docker compose up
# or docker-compose up --build if you want to rebuild the image
# this will start postgres on port 5432
# and the api on port 3007Database migrations are applied automatically on startup. After each schema change (src/schema.ts), run yarn db:generate to generate the matching migration.
Optionally seed sample API keys with yarn db:seed (idempotent, requires the app to have run once so migrations are applied).
To get start, first install all dependencies with:
yarnNext, make a copy of .env.example and rename it as .env. Then update the credentials in the file to the correct values for your
local setup.
Note: If using docker compose to start dependencies then the default .env.example value should be okay as it is.
Finally, to run the service you do:
yarn devThis should start the service to be listening on port 3007.
curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'secret: <APP_SECRET>' \
--data '{
"jsonrpc": "2.0",
"method": "get_keys",
"params": {
"app": "snapshot-hub"
},
"id": "123456789"
}'curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'secret: <APP_SECRET>' \
--data '{
"jsonrpc": "2.0",
"method": "log_req",
"params": {
"key": "<API_KEY>",
"app": "snapshot-hub"
},
"id": "123456789"
}'- Make sure to whitelist the
ownerandnamein thekeystable before generating a key. - Go to https://app.mycrypto.com/sign-message and connect your wallet (whitelisted
owneraddress) - Sign the message with keyword
generateKey. - Copy the signature and use it in the
sigparam.
curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"jsonrpc": "2.0",
"method": "generate_key",
"params": {
"sig": "<SIGNATURE>"
},
"id": "123456789"
}'Returns the caller's own active keys, including the key values and owner, and
their daily and monthly usage for the last 30 days and 12 months. Addresses
listed in admins in src/config.json get every active key and the usage of
all keys instead, to track it. Keys of other owners are replaced by their
SHA-256 hash, so admins never receive a usable key.
Authenticated with an EIP-712 signature from the owner's Snapshot alias, so no wallet prompt is needed once an alias is registered:
- Domain:
{ "name": "snapshot", "version": "0.1.4" } - Type:
GetKeys { from: address, alias: address, timestamp: uint64 } fromis the owner address,aliasis the signing alias address, andtimestampis unix seconds, within 5 minutes of server time.- The signing alias must be registered for
fromon the hub, and less than 90 days old (same window the sequencer applies).
curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"jsonrpc": "2.0",
"method": "get_keys_by_owner",
"params": {
"from": "<OWNER_ADDRESS>",
"alias": "<ALIAS_ADDRESS>",
"timestamp": 1769123456,
"sig": "<SIGNATURE>"
},
"id": "123456789"
}'Creates a new Free tier key for the caller and returns it. Authenticated like
get_keys_by_owner, with the type
CreateKey { from: address, alias: address, name: string, timestamp: uint64 }.
An owner can hold up to 10 active keys, each with a different name, and needs a
Snapshot profile with a name and an X handle (checked on the hub).
curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"jsonrpc": "2.0",
"method": "create_key",
"params": {
"from": "<OWNER_ADDRESS>",
"alias": "<ALIAS_ADDRESS>",
"name": "<NAME>",
"timestamp": 1769123456,
"sig": "<SIGNATURE>"
},
"id": "123456789"
}'Rename or delete one of the caller's active keys, authenticated like
create_key. rename_key takes key and name, signed as
RenameKey { from: address, alias: address, key: string, name: string, timestamp: uint64 }.
delete_key takes key, signed as
DeleteKey { from: address, alias: address, key: string, timestamp: uint64 }.
Deleting deactivates the key, which keeps its usage history, and frees its name.
This method is used by laser to whitelist new address
curl --location 'https://keycard.snapshot.org/' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'secret: <APP_SECRET>' \
--data '{
"jsonrpc": "2.0",
"method": "whitelist",
"params": {
"owner": "<OWNER_ADDRESS>",
"name": "<NAME>"
},
"id": "123456789"
}'Run all tests with
yarn test # Will also generate test coverage
# You can also run only E2E tests with: yarn test:e2eE2E tests require a dedicated PostgreSQL test database, named keycard_test (its name must end with _test). The app applies its own migrations at startup, so the database only needs to exist:
createdb keycard_testTest configuration are defined in test/.env.test