AG9

Use AG9 to register and verify AI agents with VeryAI Palm-backed human ownership, generate or load portable Ed25519 identities for OpenClaw, Codex, local CLI...

oyyblin@oyyblin

Install

openclaw skills install @oyyblin/ag9

ag9 — Know Your Agent

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

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.
A real model is operating — reverse CAPTCHA. Three challenge families (byte transforms, constrained generation, structured extraction) that capable LLMs can solve in seconds and naive 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 first when present. OpenClaw owns this identity file.
~/.ag9/identity.json (read/write). Used when OpenClaw identity is absent. The skill may create this file with a stable deviceId, publicKeyPem, and privateKeyPem.
Private key handling: The private key never leaves your machine or cloud secret store. Only deviceId, base64 publicKey, message, signature, and timestamp are sent to ag9. Path B (reverse CAPTCHA) does not touch identity files.
No other filesystem access. No background processes. No outbound network calls other than https://api.ag9.ai.

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	Installed skill instructions for registration, reverse CAPTCHA, verification, and API usage
Identity	`~/.openclaw/identity/device.json` or `~/.ag9/identity.json` — 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. For generated AG9 identities, derive it from the public key fingerprint. 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

Resolve identity in this order:

Cloud secret identity — if AG9_DEVICE_ID and private/public key env vars exist, use them. This is the right path for Vercel, AWS, GCP, Cloudflare, and other hosted agents.
OpenClaw identity — if ~/.openclaw/identity/device.json exists, use it.
Portable AG9 identity — otherwise load or create ~/.ag9/identity.json. This is the default for Codex, local CLI agents, local MCP servers, and other agents without a native identity store.

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 do not use OpenClaw, the recommended local identity path is:

Path: ~/.ag9/identity.json

Use the same shape:

json

{
  "deviceId": "ag9_agent_...",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "privateKeyPem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "createdAt": "2026-05-12T00:00:00.000Z",
  "provider": "ag9-local",
  "label": "local-agent"
}

For cloud agents, do not write this file on ephemeral disk. Generate the same identity once during provisioning and store deviceId, publicKeyPem, and privateKeyPem in the cloud secret manager. The runtime should load those values from environment variables or mounted secrets:

bash

AG9_DEVICE_ID=ag9_agent_...
AG9_PUBLIC_KEY_PEM_B64=base64-encoded-public-pem
AG9_PRIVATE_KEY_PEM_B64=base64-encoded-private-pem

Plain multiline AG9_PUBLIC_KEY_PEM and AG9_PRIVATE_KEY_PEM are also valid when the platform supports multiline secrets.

Build the challenge (step-by-step)

Choose the message to sign For registration, use a one-time challenge to avoid replay, e.g.:
- ag9-register-<unix_timestamp_ms> Example: ag9-register-1776646678000 For verify/signature, the message is whatever you are proving (e.g. a nonce from a third party).
Sign the message with your Ed25519 private key. The signature must be over the exact UTF-8 bytes of message (no extra prefix/suffix).
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()).
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, OpenClaw or `~/.ag9`

javascript

const crypto = require("crypto");
const fs = require("fs");
const path = require("path");

function base64url(buffer) {
  return Buffer.from(buffer)
    .toString("base64")
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/g, "");
}

function pemFromEnv(name) {
  if (process.env[name]) {
    return process.env[name];
  }
  const b64 = process.env[`${name}_B64`];
  return b64 ? Buffer.from(b64, "base64").toString("utf8") : "";
}

function loadOrCreateIdentity() {
  const envIdentity = {
    deviceId: process.env.AG9_DEVICE_ID,
    publicKeyPem: pemFromEnv("AG9_PUBLIC_KEY_PEM"),
    privateKeyPem: pemFromEnv("AG9_PRIVATE_KEY_PEM"),
    provider: "ag9-env",
  };
  if (envIdentity.deviceId && envIdentity.publicKeyPem && envIdentity.privateKeyPem) {
    return envIdentity;
  }

  const openClawPath = path.join(process.env.HOME, ".openclaw/identity/device.json");
  if (fs.existsSync(openClawPath)) {
    return JSON.parse(fs.readFileSync(openClawPath, "utf8"));
  }

  const ag9Path = path.join(process.env.HOME, ".ag9/identity.json");
  if (fs.existsSync(ag9Path)) {
    return JSON.parse(fs.readFileSync(ag9Path, "utf8"));
  }

  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
  const publicKeyDer = publicKey.export({ type: "spki", format: "der" });
  const fingerprint = base64url(crypto.createHash("sha256").update(publicKeyDer).digest()).slice(0, 32);
  const identity = {
    deviceId: `ag9_agent_${fingerprint}`,
    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }),
    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }),
    createdAt: new Date().toISOString(),
    provider: "ag9-local",
    label: "local-agent",
  };

  fs.mkdirSync(path.dirname(ag9Path), { recursive: true, mode: 0o700 });
  fs.writeFileSync(ag9Path, JSON.stringify(identity, null, 2), { mode: 0o600 });
  return identity;
}

const identity = loadOrCreateIdentity();

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:

Generate a challenge string, e.g. ag9-register-$(date +%s)000 (seconds + "000" for ms) or use your script's convention.
Run the script to sign that message and get the challenge JSON.
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.

bash

curl -X POST https://api.ag9.ai/v1/agent/register/init \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "my-agent-device-id",
    "publicKey": "<base64-DER-SPKI-Ed25519>",
    "message": "ag9-register-1776646678000",
    "signature": "<base64-Ed25519-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:

bash

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:

bash

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:

bash

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):

bash

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

bash

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):

json

{
  "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:

bash

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

Response (200):

json

{
  "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`

json

{
  "data": "<base64 of 256 random bytes>",
  "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`

json

{
  "document": "<malformed HTML/JSON/XML blob with authoritative and decoy values>",
  "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", <section data-kind="live">, <item status="current">, <main>. Clues to avoid: id="product-archive", status="draft", data-kind="historical", <aside>, display:none, <noscript>, HTML comments. Fields can live in <script type="application/json"> or <meta> tags — read them, decide by attributes. Time limit 30s.

`constrained_gen`

json

{
  "topic": "ocean waves",
  "lines": 4,
  "ascii_target": 419,
  "word_count": 20,
  "difficulty": "medium"
}

Answer: A plain-text block of exactly lines non-empty lines totaling word_count words, where the sum of ASCII codes of the first character of each trimmed line equals ascii_target (lowercase a=97 through z=122). Recommended approach: choose first letters l_1..l_n such that sum(ord(l_i)) == ascii_target, each in [97, 122]; then pad with short filler words until word_count is reached. Time limit 20s.

4. Verify the JWT offline

Any relying party can verify the attestation without calling ag9 back:

bash

curl -s https://api.ag9.ai/.well-known/jwks.json

Then verify the JWT signature using the returned Ed25519 public key. Cache-Control is public, max-age=3600.

When to use which path

Need	Path
Prove a human owns this agent	A — registration + `/agent/verify/device/{deviceId}`
Prove a capable LLM is operating (no human/account needed)	B — `/challenge` + `/verify`
Prove both	Run A first, then B on each outbound request
Third-party wants to check your agent	They call either `/agent/verify/device/{id}` (A) or accept a JWT you present (B)

API reference

Base URL: https://api.ag9.ai/v1 (human-ownership endpoints) Base URL (root): https://api.ag9.ai (reverse-CAPTCHA endpoints) Local: http://localhost:3000

Endpoints

Method	Endpoint	Auth	Description
POST	`/v1/agent/register/init`	None	Start registration session; returns `sessionId`, `registrationUrl`, `expiresAt`.
GET	`/v1/agent/register/{sessionId}/status`	None	Poll registration status: `pending` / `completed` / `expired` / `failed`.
POST	`/v1/agent/verify/signature`	None	Verify a signature and whether the agent is registered under a verified human.
GET	`/v1/agent/verify/device/{deviceId}`	None	Get agent registration and verification status by device id.
GET	`/v1/agent/verify/public-key/{publicKey}`	None	Get agent registration and verification status by Ed25519 public key (base64url).
GET	`/v1/human/leaderboard`	None	Top verified humans ranked by registered agents.
POST	`/challenge[?type=...]`	None	Issue a single-use reverse-CAPTCHA challenge.
POST	`/verify`	None	Submit `{token, solution}`; receive capability JWT.
GET	`/.well-known/jwks.json`	None	JWKS for offline JWT verification.

Error shape

json

{
  "error": "Human-readable message",
  "code": "optional_code",
  "details": {}
}

Error codes

Code	Meaning
400	Bad request (invalid or missing fields).
404	Session or device not found.
409	Agent already registered (device_id already exists).
429	Rate limit exceeded (10 req/min per IP on /challenge and /verify).
500	Server error.

What this proves

After a successful run through Path A and/or B, a relying party can conclude:

Human ownership (A) — The agent is bound to a human who passed VeryAI palm verification. Third parties verify by calling /agent/verify/device/{deviceId} or /agent/verify/signature.
Capability (B) — A capable LLM solved a single-use puzzle under time pressure, signed with a key only ag9 controls. Third parties verify the JWT offline via JWKS.
Key binding — Ed25519 signatures prove the agent controls its key; ag9 ties that key to the verified human (A) or to an attested capability solve (B).

When to use this skill

Registering an OpenClaw (or other) agent under a human owner before interacting with a platform that requires KYA.
Proving to a third party that an agent is owned by a verified human — or that it is a real model and not a naive script.
Running a self-check to confirm registration and verification are healthy.

Need help?

API base: https://api.ag9.ai
Homepage: https://ag9.ai
Interactive demo: https://ag9.ai/demo
OpenAPI spec: https://api.ag9.ai/openapi/v1.yaml

AG9

Install

ag9 — Know Your Agent

What this skill accesses on your machine

Key files

Security

Path A: Human ownership (agent ↔ human binding)

Generating the AgentChallenge

Where identity comes from

Build the challenge (step-by-step)

Example: Node.js, OpenClaw or ~/.ag9

Using a script

Quick start — human ownership

1. Start registration (agent-initiated)

2. Human completes verification

3. Poll registration status

4. Verify signatures or look up an agent

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

Endpoint summary

1. Request a challenge

2. Solve and submit

3. Family-specific payloads

byte_transform

structured_extraction

constrained_gen

4. Verify the JWT offline

When to use which path

API reference

Endpoints

Error shape

Error codes

What this proves

When to use this skill

Need help?

Related skills

Example: Node.js, OpenClaw or `~/.ag9`

`byte_transform`

`structured_extraction`

`constrained_gen`