humanode-agentlink

name

humanode-agentlink

description

AgentLink gives an AI agent a verified, human-backed on-chain identity. Use it to link and register an agent wallet with a biomapped human owner in BiomapperAgentRegistry, verify active AgentLink status on Base mainnet, sign HTTP requests with the agent key, validate agentlink headers, and access supported partner endpoints. Covers the AgentLink CLI encrypted keystore and external signers through the SDK.

AgentLink Skill

AgentLink gives an AI agent a verified, human-backed on-chain identity. With this skill the agent can sign any HTTP request, appear in the on-chain registry as a trusted agent, and access free partner endpoints on Base mainnet.

Skill Condition

An agent holds the AgentLink Skill when both are true:

• Linked & registered — the agent wallet is linked to a biomapped human owner, which is the same on-chain write that registers it in the BiomapperAgentRegistry. agentlink status --network base --json reports "linked": true and "active": true.
• Signing — the agent can produce a valid agentlink header, signed by the agent key (held in the encrypted CLI keystore, or by an external signer for the SDK).

---

Phase 1 — Acquire

Run the CLI with npx (no global install needed) and store your agent private key. No on-chain write happens yet — registration is created during the Linker step in Phase 2.

# Store the agent private key in the encrypted local keystore.
# You will be prompted for the key and a password.
npx @techdigger/humanode-agentlink-cli keystore set

# Show the agent wallet address derived from the stored key
npx @techdigger/humanode-agentlink-cli keystore address

Prefer a global install? npm install -g @techdigger/humanode-agentlink-cli makes the agentlink command available directly (this guide uses the short agentlink ... form from here on). For CI or secret-manager flows use --private-key-stdin instead of the interactive keystore.

---

Phase 2 — Verify

The human owner must complete biomapping and link their wallet to the agent. The agent cannot complete this phase alone — it generates a URL for the human to open.

Human prerequisites

The human owner must do these two steps first:

1. Open Biomapper and complete biomapping.
2. Bridge their biomapping to Base.

Generate the Linker URL

Replace 0x<OWNER_ADDRESS> with the human owner's biomapped wallet address:

agentlink link --owner 0x<OWNER_ADDRESS> --network base --open

This prints (and optionally opens) a self-contained URL. Send it to the human owner. They open it, review the request in the AgentLink Linker at app.agentlink.id, and sign the link transaction.

Confirm the skill is active

agentlink status --network base --json

When the JSON output shows "linked": true and "active": true, the skill is acquired and Phase 2 is complete.

active tracks the owner's biomapping. If the linked owner wallet stops being biomapped in the current Biomapper generation, status flips to "active": false and freemium access pauses until they re-biomap — the link itself is preserved.

---

Phase 3 — Use

Sign requests with the SDK

Add the SDK to your agent project (this is the @techdigger/humanode-agentlink runtime package — separate from the @techdigger/humanode-agentlink-cli used above):

npm install @techdigger/humanode-agentlink

createAgentLinkClient returns a fetch wrapper that attaches the agentlink header to every request automatically. Give it the agent key in whichever form matches how your agent already holds it.

Option A — raw private key. Simplest for a self-hosted agent that keeps its key in an environment variable or secret:

import { createAgentLinkClient } from '@techdigger/humanode-agentlink'

const { fetch: agentFetch } = createAgentLinkClient({
  network: 'base',
  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
})

Option B — external signer. Use this when the key lives in a KMS, HSM, or secret manager and you never want it in your process — pass the agent's public address plus a sign callback:

const { fetch: agentFetch } = createAgentLinkClient({
  network: 'base',
  address: agentAddress, // your agent's public address
  sign: (message) => signer.sign(message), // key stays in KMS / HSM / secret manager
})

Either client signs and sends the request the same way:

// The agentlink header is attached automatically
const response = await agentFetch('https://api.xona-agent.com/base-main/image/nano-banana', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'a futuristic city at sunset', aspect_ratio: '1:1', referenceImage: [] }),
})

To build just the header value for use with curl, axios, or any HTTP client, buildAgentLinkHeader takes the same two option shapes:

import { buildAgentLinkHeader } from '@techdigger/humanode-agentlink'

// Option A — raw key
const header = await buildAgentLinkHeader('https://api.xona-agent.com/base-main/image/nano-banana', {
  network: 'base',
  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
})

// Option B — external signer
const header = await buildAgentLinkHeader('https://api.xona-agent.com/base-main/image/nano-banana', {
  network: 'base',
  address: agentAddress,
  sign: (message) => signer.sign(message),
})
// pass as: agentlink: <header>

Keep the agent key wherever you already manage secrets. A raw key in env is fine for a self-hosted agent that controls its own host — just keep it out of source control and logs. If the key lives in a KMS or HSM, use Option B so it never crosses that boundary.

Smoke-test a signed request

agentlink request https://api.xona-agent.com/base-main/image/nano-banana --network base

agentlink request sends only the agentlink header — no request body. Use it to verify the agent is linked and the signature is accepted. For real POST requests with a JSON body use the SDK above.

---

Free Endpoints (Base mainnet, live today)

These partner endpoints are free for linked agents. Full recipes and the machine-readable index are at agentlink.id/docs/freemium-endpoints.

XONA — creative AI agent

Endpoint	What it does
POST https://api.xona-agent.com/base-main/video/short-generation	Generate a short video from a text prompt
POST https://api.xona-agent.com/base-main/image/nano-banana	Generate an image from a text prompt

Headers required: Content-Type: application/json and agentlink: <signed payload>.

WURK — tasking marketplace

WURK allows one freemium use total across both endpoints.

Endpoint	What it does
GET https://wurkapi.fun/base/agentlink/xraid/xverified/small	Commission an X (Twitter) raid
GET https://wurkapi.fun/base/agentlink/agenttohuman	Commission an agent-to-human job

WURK uses a server-issued challenge flow — see agentlink.id/docs/freemium-endpoints for the full signing recipe.

---

Network Reference

Profile	Chain	Registry
base (mainnet)	eip155:8453	0x7Ef35Bf180dcDAA5AB6cdEC7e9DED6230aD12263