Authentication and signing

Every call in both directions carries an Ed25519 signature. There are no API keys, bearer tokens or shared secrets.

The keys

• Ed25519 only, as PEM: private keys in PKCS#8 (-----BEGIN PRIVATE KEY-----), public keys as SPKI (-----BEGIN PUBLIC KEY-----). Both are what openssl genpkey -algorithm ed25519 and openssl pkey -pubout produce. RSA is not accepted.
• Two active keys per operator at any time, so you can rotate without downtime: a signature valid under either key is accepted.
• We always publish two RGS wallet keys, current and standby. Your wallet must accept a signature from either, at all times. On a compromise we switch to standby immediately with no action on your side. A planned rotation is announced at least 14 days ahead.
• One key per purpose per environment. Never reuse a sandbox key in production.

Signing a request to the operator API

Send these headers:

There are two signing forms. Use the second one if you can.

Engine form: the body only

The signature covers the exact bytes of the request body. For a GET it covers the empty string. This is the form Engine uses, so an Engine-written client keeps working. It proves who sent the call but not when, and it does not cover the path or query, so the RGS only uses query parameters for read filters.

Full-request form (A9): method, path, query and a timestamp

Add the header RuneCode-Timestamp: <unix seconds> and sign this string (UTF-8):

METHOD "\n" PATH "\n" CANONICAL_QUERY "\n" TIMESTAMP "\n" BODY

• PATH is the path as sent, without host.
• CANONICAL_QUERY: decode each name=value pair (+ means space), sort by name then value (byte order), then re-encode with RFC 3986 (letters, digits and -._~ stay literal, everything else is %XX in upper case) and join with &. Empty if there is no query.
• TIMESTAMP is the same text you send in the header, and must be within 60 seconds of our clock.
• Required for every /runecode/v1/* call. Optional but recommended on the Engine endpoints (/v1/*): when a request carries RuneCode-Timestamp, the signature must be the full-request form. An operator can make it mandatory.

The SDKs implement both; fullRequestSigning: true turns the second one on for the Engine endpoints too.

Serialize the JSON body once, sign those bytes, and send those same bytes. Re-serializing between signing and sending is the most common cause of 401.

Reference (Node, no libraries)

import { createPrivateKey, sign } from "node:crypto";
const key = createPrivateKey(process.env.OPERATOR_PRIVATE_KEY_PEM!);
const body = JSON.stringify(payload);                          // serialize ONCE
const signature = sign(null, Buffer.from(body), key).toString("base64"); // null = pure Ed25519, no pre-hash
// send `body` with X-Operator and X-Signature

Verifying a request from the RGS (your wallet)

The RGS sends x-operator (your slug) and x-signature on every wallet call except GET /health. The signature covers the raw body bytes.

1. Read the raw body.
2. Check x-operator is your slug; otherwise answer 401 ERR_ATE.
3. Verify x-signature over the raw bytes against each RGS key (current and standby); accept if any verifies.
4. Only then parse the JSON.

A signature proves origin, not freshness. Safety against replays comes from idempotency on the transaction ids, not from timestamps (see Implementing the wallet).

Test vectors

vectors/signing.json holds a test key and known answers: Ed25519 is deterministic, so the same body always gives the same signature. Every SDK must reproduce them exactly; use them to check your own implementation.

Common mistakes

• Signing a pretty-printed or re-ordered body, then sending a different serialization.
• Using the standard Base64 alphabet without padding, or URL-safe Base64. It is standard, with padding.
• Pre-hashing the body (Ed25519 here is the pure form, RFC 8032, no pre-hash).
• Verifying after parsing instead of before.
• Trusting only one RGS key, which breaks during an emergency rotation.