Integration Quickstart

The fastest way to test Keywave end to end: create an account, get an API key, enroll once, verify with a fresh phrase, and stamp the result.

For deeper reference, see the main docs, Verify & Stamp, and /openapi.json.

Pilot noteDuring the pilot phase, some first requests may feel slightly slower while upstream systems warm up. If a first attempt stalls, retry once with normal backoff before assuming there is an integration problem.

1) Create an account

Start by creating your Keywave account and opening the developer dashboard.

From there, you can create an API key and begin testing immediately.

2) Get your API key

Generate an API key from your dashboard and keep it server side only.

Required headers

x-api-key: <YOUR_API_KEY>
Content-Type: application/json
For sandbox testing, also send x-keywave-env: sandbox

3) Enroll once

Enroll creates the user’s protected voice template. This is usually done once before verification.

curl -s https://api.keywave.io/api/v1/enroll \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "x-keywave-env: sandbox" \
  -d '{
    "wallet":"<WALLET_ID>",
    "audioUrl":"https://<your-signed-or-public>/voice/enroll.m4a",
    "projection_id":"p0",
    "params_version":"v1"
  }' | jq

4) Verify with a fresh phrase

First request a phrase, then record the user speaking that phrase, then submit the audio for verification.

Get phrase

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

Verify

curl -s https://api.keywave.io/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "x-keywave-env: sandbox" \
  -d '{
    "wallet":"<WALLET_ID>",
    "audioUrl":"https://<your-signed-or-public>/voice/verify.m4a",
    "projection_id":"p0",
    "params_version":"v1",
    "phrase_id":"pc_xxx"
  }' | jq

5) Stamp the proof

After a successful verification, submit the returned verification_id to the stamp endpoint.

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

What success looks like

Enroll returns ok: true
Verify returns ok: true, success: true, and gates.all_passed: true
Stamp returns ok: true with a Solana transaction signature or explorer URL

What failure looks like

401 means the API key is missing or invalid
400 on verify often means the phrase is missing, expired, or already used
404 on verify usually means no enrolled voice template exists yet
429 means retry later using Retry-After
A verify response with gates.all_passed: false means the user was processed, but the proof did not pass the checks

Fastest way to test

If you want to validate everything quickly before wiring your own UI, use the Playground. Then move to your server side integration once your API key, request flow, and response handling look correct.