Skip to content
snapshot-labsPublic

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

2 watching

Forks

Repository files navigation

Keycard API

This API is responsible for managing keys and counts for all snapshot APIs

Limits

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

Getting Started (Local Development)

This API depends on a couple of services:

  • Node.js (>= v22.6.0)
  • PostgreSQL (v18 — older versions likely work but are untested)

Docker

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 3007

Database 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).

Local

To get start, first install all dependencies with:

yarn

Next, 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 dev

This should start the service to be listening on port 3007.

Using the API

get_keys

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"
}'

log_req

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"
}'

generate_key

  • Make sure to whitelist the owner and name in the keys table before generating a key.
  • Go to https://app.mycrypto.com/sign-message and connect your wallet (whitelisted owner address)
  • Sign the message with keyword generateKey.
  • Copy the signature and use it in the sig param.
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"
}'

get_keys_by_owner

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 }
  • from is the owner address, alias is the signing alias address, and timestamp is unix seconds, within 5 minutes of server time.
  • The signing alias must be registered for from on 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"
}'

create_key

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_key and delete_key

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.

whitelist

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"
}'

Test

Run all tests with

yarn test # Will also generate test coverage
# You can also run only E2E tests with: yarn test:e2e

E2E 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_test

Test configuration are defined in test/.env.test

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages