Keywave API Docs (Preview)

Keywave verifies voiceprints using irreversible SHA-256 hashes — no raw audio is sent to the API.

Quickstart

Two calls: /enroll then /verify. Optionally /stamp to anchor a proof on Solana.

# 1) Enroll a wallet with a hash
curl -s https://api.keywave.io/api/v1/enroll \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","embedding_hash":"<SHA256_HEX>"}' | jq

# 2) Verify by comparing a probe hash
curl -s https://api.keywave.io/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","probe_hash":"<SHA256_HEX>"}' | jq

Hashing (client-side)

Hash locally. Never send raw audio. Example (browser):

async function sha256Hex(text) {
  const enc = new TextEncoder().encode(text);
  const buf = await crypto.subtle.digest('SHA-256', enc);
  return [...new Uint8Array(buf)].map(b=>b.toString(16).padStart(2,'0')).join('');
}

Endpoints

POST /api/v1/enroll

Body: { wallet, embedding_hash }

curl -s https://api.keywave.io/api/v1/enroll \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","embedding_hash":"<SHA256_HEX>"}' | jq

POST /api/v1/verify

Body: { wallet, probe_hash }

curl -s https://api.keywave.io/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","probe_hash":"<SHA256_HEX>"}' | jq

POST /api/v1/stamp (on-chain proof)

Anchors a receipt on Solana (Memo). Returns a transaction signature and Explorer link.

curl -s https://api.keywave.io/api/v1/stamp \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>"}' | jq

# Example response
{
  "ok": true,
  "wallet": "test_wallet_1",
  "anchor_tx": "5Zc7...abc",
  "explorer_url": "https://explorer.solana.com/tx/5Zc7...abc?cluster=devnet"
}

Errors

All endpoints return a consistent error shape:{ ok:false, code, message }

{ "ok": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again later.", "retry_after": "ISO" }

{ "ok": false, "code": "INSUFFICIENT_FUNDS", "message": "Fee payer has insufficient SOL on current cluster.", "fee_payer": "pubkey", "cluster": "devnet" }

Error Schema

All Keywave API errors follow a consistent JSON shape so you can handle them reliably in your code.

{
  "ok": false,
  "code": "RATE_LIMIT",
  "message": "Too many requests"
}

Common code values include:
• RATE_LIMIT – Too many requests per minute.• UNAUTHORIZED – Invalid or missing API key.• SERVER_ERROR – Unexpected backend failure.

Contact

For pilot access or developer support, email us at support@keywave.io.