AG9

---

name: ag9 version: 1.1.0 description: Know Your Agent — verifiable human ownership + reverse CAPTCHA for OpenClaw agents, powered by VeryAI palm verification. homepage: https://ag9.ai requires: config: - ~/.openclaw/identity/device.json env: - HOME metadata: category: identity api_base_human_ownership: https://api.ag9.ai/v1 api_base_reverse_captcha: https://api.ag9.ai reads_private_key: true

---

ag9 — Know Your Agent

ag9 proves two things about an agent that no other layer proves together:

1. A real human owns this agent — palm-bound via VeryAI. The human scans their palm once; the agent is now cryptographically tied to a verified person. 2. A real model is operating — reverse CAPTCHA. Three challenge families (byte transforms, constrained generation, structured extraction) that capable LLMs can solve in seconds and humans/scripts cannot.

Both live at https://api.ag9.ai. Note the two base URLs:

Path A (human ownership) uses https://api.ag9.ai/v1/agent/...

Path B (reverse CAPTCHA) uses https://api.ag9.ai/challenge, /verify, and /.well-known/jwks.json at the root (not under /v1) to match existing OpenClaw/monkey-api integrations.

This URL split is intentional, not a typo — both endpoints are served by the same ag9-api service.

What this skill accesses on your machine

~/.openclaw/identity/device.json (read). Used for Path A only. The skill reads deviceId, publicKeyPem, and privateKeyPem to sign registration/verification challenges. The private key never leaves your machine — only the base64 publicKey, message, and signature are sent to ag9. Path B (reverse CAPTCHA) does not touch this file.

No other filesystem access. No disk writes. No background processes. No outbound network calls other than https://api.ag9.ai.

Declared in the skill manifest as requires.config, so install tooling can prompt before first use.

> CRITICAL: Never open browsers > > Do not use open, xdg-open, start, or any command that opens a browser. Always output the registration URL as a text or markdown link for the user to click. > > - WRONG: open "https://api.very.org/oauth2/..." > - CORRECT: "Open this link to complete verification: https://api.very.org/oauth2/..."

Key files

| File | Purpose | | ------------ | --------------------------------------------------------------------------------------------- | | SKILL.md | https://ag9.ai/skill.md — registration flow, reverse CAPTCHA, verification, full API | | HEARTBEAT.md | https://ag9.ai/heartbeat.md — periodic checklist: registration status, capability attestation | | Identity | ~/.openclaw/identity/device.json — OpenClaw deviceId and keys (never send private key) |

Security

Private key: Used to sign the challenge. Never send the private key to ag9 or any server; only send publicKey, message, and signature.

Registration URL: Single-use and short-lived. Give it only to the human owner who will complete VeryAI palm verification.

deviceId: Use a stable identifier (e.g. from your identity store or hash of public key). It ties the agent to the registration and is used for lookup and verification.

Challenge token (reverse CAPTCHA): HMAC-signed, 15 seconds, single-use. The token carries the answer hash so the server does not keep any per-request state.

Capability JWT: Ed25519-signed attestation returned after a successful /verify. Public key at GET /.well-known/jwks.json so any party can verify offline.

---

Path A: Human ownership (agent ↔ human binding)

Use this when you need a third party to know the agent is owned by a verified human.

Generating the AgentChallenge

The AgentChallenge is a signed payload that shows you control an Ed25519 key. It has the shape used by standard OpenClaw identity flows: deviceId, publicKey, message, signature, timestamp. Generate it once and send it to /agent/register/init or /agent/verify/signature.

#### Where identity comes from (OpenClaw)

If you run on OpenClaw, device identity is stored at:

Path: ~/.openclaw/identity/device.json

That file contains (never send privateKeyPem to any server):

| Field | Use | | --------------- | ------------------------------------------------------------------------ | | deviceId | Use as deviceId in the challenge. Stable id for this agent/device. | | publicKeyPem | Use to derive publicKey (see below). | | privateKeyPem | Use only locally to sign the message. Never include in API requests. |

If you don't use OpenClaw, use your own identity store; ensure you have a stable deviceId, an Ed25519 key pair, and that you sign the exact string you send as message.

#### Build the challenge (step-by-step)

1. Choose the message to sign For registration, use a one-time challenge to avoid replay, e.g.: - ag9-register- Example: ag9-register-1776646678000 For verify/signature, the message is whatever you are proving (e.g. a nonce from a third party).

2. Sign the message with your Ed25519 private key. The signature must be over the exact UTF-8 bytes of message (no extra prefix/suffix).

3. Encode for the API: - publicKey: Ed25519 public key in SPKI DER form, then base64 (no PEM wrapper). - signature: Raw Ed25519 signature bytes, base64. - timestamp: Unix time in milliseconds when the challenge was created (e.g. Date.now()).

4. JSON body (AgentChallenge): - deviceId — from your identity (e.g. device.json) - publicKey — base64 DER SPKI - message — exact string that was signed - signature — base64 signature - timestamp — number (ms)

#### Example: Node.js

const crypto = require("crypto");
const fs = require("fs");
const identityPath = ${process.env.HOME}/.openclaw/identity/device.json;
const identity = JSON.parse(fs.readFileSync(identityPath, "utf8"));
const message = ag9-register-${Date.now()};
const privateKey = crypto.createPrivateKey(identity.privateKeyPem);
const signature = crypto.sign(null, Buffer.from(message, "utf8"), privateKey);
const publicKeyDer = crypto
  .createPublicKey(identity.publicKeyPem)
  .export({ type: "spki", format: "der" });
const challenge = {
  deviceId: identity.deviceId,
  publicKey: publicKeyDer.toString("base64"),
  message,
  signature: signature.toString("base64"),
  timestamp: Date.now(),
};
// POST challenge to https://api.ag9.ai/v1/agent/register/init

#### Using a script

If you have a script that already produces an AgentChallenge (e.g. signs a message and outputs JSON with deviceId, publicKey, message, signature, timestamp), you can reuse it for ag9:

1. Generate a challenge string, e.g. ag9-register-$(date +%s)000 (seconds + "000" for ms) or use your script's convention. 2. Run the script to sign that message and get the challenge JSON. 3. POST that JSON to https://api.ag9.ai/v1/agent/register/init.

Same challenge format works for POST /agent/verify/signature when verifying a signature remotely.

Quick start — human ownership

#### 1. Start registration (agent-initiated)

Build an AgentChallenge as above, then send it to ag9 to create a session and get a registration URL.

curl -X POST https://api.ag9.ai/v1/agent/register/init \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "my-agent-device-id",
    "publicKey": "",
    "message": "ag9-register-1776646678000",
    "signature": "",
    "timestamp": 1776646678000
  }'

Response (201):

sessionId — use to poll status

registrationUrl — output this as a link for the human; do not open it in a browser

expiresAt — session expiry (ISO 8601)

If the agent is already registered (deviceId exists), the API returns 409 Conflict.

#### 2. Human completes verification

Tell the human owner to open the registrationUrl in their browser. They will go through VeryAI's palm verification via OAuth. When they finish, the agent is registered under their ownership.

#### 3. Poll registration status

Poll until the human has completed or the session has expired:

curl "https://api.ag9.ai/v1/agent/register/SESSION_ID/status"

Response: status is one of pending | completed | expired | failed. When status is completed, the response includes deviceId and registration (e.g. publicKey, registeredAt).

#### 4. Verify signatures or look up an agent

Verify a signature — check that a message was signed by the given key and whether that agent is registered under a verified human:

curl -X POST https://api.ag9.ai/v1/agent/verify/signature \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "...",
    "publicKey": "...",
    "message": "...",
    "signature": "...",
    "timestamp": 1776646678000
  }'

Response: verified (signature valid), registered (agent under verified human).

Look up an agent by device id — get registration and verification status:

curl "https://api.ag9.ai/v1/agent/verify/device/DEVICE_ID"

Response: registered, verified, humanId, and optionally registeredAt.

Look up an agent by public key (base64 DER SPKI):

curl "https://api.ag9.ai/v1/agent/verify/public-key/$(printf '%s' "$PUBKEY_B64" | jq -sRr @uri)"

---

Path B: Reverse CAPTCHA (prove a real model is operating)

Use this when a relying party needs to confirm the requester is a capable agent (not a naive script), independent of any human binding. Stateless, no account needed.

Endpoint summary

| Method | Path | Purpose | | ------ | ------------------------ | -------------------------------------------------------------------------- | | POST | /challenge | Issue a single-use HMAC-signed challenge (15s TTL). | | POST | /verify | Submit {token, solution}; receive an Ed25519-signed capability JWT. | | GET | /.well-known/jwks.json | Public key (JWKS) for offline JWT verification. |

These live at the root, not under /v1, to match existing OpenClaw/monkey-api integrations.

1. Request a challenge

curl -s -X POST https://api.ag9.ai/challenge \
  -H "Content-Type: application/json" -d '{}'

Optional ?type=byte_transform|structured_extraction|constrained_gen pins the family. Omit for random.

Response (200):

{
  "challenge_id": "string",
  "challenge_type": "byte_transform | structured_extraction | constrained_gen",
  "difficulty": "medium",
  "payload": { /* shape depends on challenge_type — see below */ },
  "token": "base64url-encoded HMAC-signed token carrying the answer hash",
  "expires_at": 1776646678,
  "time_limit_secs": 30
}

2. Solve and submit

Compute the answer from payload (family-specific — see next section). Submit:

curl -s -X POST https://api.ag9.ai/verify \
  -H "Content-Type: application/json" \
  -d '{ "token": "...", "solution": "..." }'

Response (200):

{
  "success": true,
  "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

The JWT is a capability attestation the relying party can verify offline using the public key at /.well-known/jwks.json. Claims include iss (api.ag9.ai), sub (agent_capability_attestation), challenge_type, difficulty, solved_at, solve_time_ms.

3. Family-specific payloads

#### byte_transform

{
  "data": "",
  "instructions": [
    "Transform every byte by XOR-ing it with 19 (decimal).",
    "Rotate all bytes left by 192 positions (with wraparound).",
    "Starting at byte 5, going up to byte 66, reverse the sub-array end to end."
  ]
}

Answer: Apply the transforms in order to the decoded bytes, then return sha256(final_bytes) as lowercase hex (64 chars). Typical approach: LLM writes Python, agent executes it. Time limit 30s.

#### structured_extraction

{
  "document": "",
  "fields": ["author_name", "price_usd", "publish_date"]
}

Answer: Extract each field's authoritative value, join with | (pipe), in the exact order listed. The document mixes current and stale/decoy values of the same type. Context clues to prefer: data-verified="true", data-primary="true", data-source="authoritative", data-kind="live", id="product-current",

, ,

. Clues to avoid: id="product-archive", status="draft", data-kind="historical",

💬