@open-agent-id/sdk

JavaScript/TypeScript SDK for Open Agent ID -- register, sign, and verify AI agent identities on-chain.

Installation

npm install @open-agent-id/sdk

Requires Node.js >= 18.

Quick Start

The most common use case is adding agent authentication headers to outbound requests:

import { signAgentAuth } from "@open-agent-id/sdk";

const headers = signAgentAuth(
  "did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
  privateKey, // Uint8Array (32 bytes)
);
// Returns object with:
//   "X-Agent-DID":       "did:oaid:base:0x1234..."
//   "X-Agent-Timestamp": "1708123456"
//   "X-Agent-Nonce":     "a3f1b2c4d5e6f7089012abcd"
//   "X-Agent-Signature": "<base64url signature>"

const res = await fetch("https://api.example.com/v1/tasks", {
  method: "POST",
  headers,
  body: JSON.stringify({ task: "search" }),
});

Registry Client

import { RegistryClient } from "@open-agent-id/sdk";

const client = new RegistryClient(); // defaults to https://api.openagentid.org

All methods

| Method | Auth required | Description | |---|---|---| | client.requestChallenge(walletAddress) | No | Request a wallet auth challenge | | client.verifyWallet(walletAddress, challengeId, signature) | No | Verify wallet signature, returns auth token | | client.registerAgent(token, opts) | Yes | Register a new agent (opts: { name, publicKey, capabilities? }) | | client.getAgent(did) | No | Look up an agent by DID | | client.listAgents(token, opts?) | Yes | List agents owned by the authenticated wallet | | client.updateAgent(did, auth, updates) | Yes | Update agent metadata | | client.revokeAgent(did, token) | Yes | Revoke an agent identity | | client.rotateKey(did, token, publicKey) | Yes | Rotate an agent's public key | | client.deployWallet(did, token) | Yes | Deploy an on-chain smart wallet for an agent | | client.getCredit(did) | No | Look up an agent's credit score | | client.verifySignature(did, domain, payload, signature) | No | Verify a signature against the agent's registered key |

Wallet auth flow

// 1. Request challenge
const { challengeId, challengeText } = await client.requestChallenge(walletAddress);

// 2. Sign the challenge text with your wallet (e.g. via ethers.js)
// const walletSignature = await wallet.signMessage(challengeText);

// 3. Verify and get auth token
const token = await client.verifyWallet(walletAddress, challengeId, walletSignature);

Register an agent

const agent = await client.registerAgent(token, {
  name: "my-agent",
  publicKey: base64urlPublicKey,
  capabilities: ["search", "summarize"],
});

Look up and list agents

const info = await client.getAgent("did:oaid:base:0x1234...");
const { agents, nextCursor } = await client.listAgents(token);

Manage agents

await client.updateAgent(did, { token }, { name: "new-name" });
await client.rotateKey(did, token, newPublicKey);
await client.revokeAgent(did, token);
await client.deployWallet(did, token);

Credit Score

const credit = await client.getCredit("did:oaid:base:0x1234567890abcdef1234567890abcdef12345678");
console.log(credit.credit_score); // 300
console.log(credit.level);       // "verified"

HTTP Signing

Sign an HTTP request

import { signHttpRequest, verifyHttpSignature } from "@open-agent-id/sdk";

const headers = await signHttpRequest(
  privateKey,          // Uint8Array (32 bytes)
  "POST",
  "https://api.example.com/v1/tasks",
  new TextEncoder().encode('{"task":"search"}'),
);
// headers = {
//   "X-Agent-Timestamp": "1708123456",
//   "X-Agent-Nonce": "a3f1b2c4d5e6f7089012abcd",
//   "X-Agent-Signature": "<base64url signature>"
// }

Verify an HTTP signature

const valid = verifyHttpSignature(
  publicKey,           // Uint8Array (32 bytes)
  "POST",
  "https://api.example.com/v1/tasks",
  bodyBytes,           // Uint8Array | null
  timestamp,           // number (unix seconds)
  nonce,               // string
  signature,           // Uint8Array
);

Use the Signer daemon

import { Signer, Agent } from "@open-agent-id/sdk";

const signer = await Signer.connect("/tmp/oaid-signer.sock");
const agent = new Agent({
  keyId: "default",
  signer,
  did: "did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
});

const res = await agent.http.post("https://api.example.com/v1/tasks", {
  task: "search",
});

Message Signing

Sign a P2P message

import { signMessage, verifyMessageSignature } from "@open-agent-id/sdk";

const signature = await signMessage(
  privateKey,
  "task.request",                          // message type
  "msg-001",                               // message ID
  "did:oaid:base:0xaaaa...aaaa",           // from DID
  ["did:oaid:base:0xbbbb...bbbb"],         // to DIDs
  null,                                    // ref
  null,                                    // timestamp (auto)
  null,                                    // expiresAt
  { task: "summarize", url: "https://..." }, // body
);

E2E Encryption

import { encryptFor, decryptFrom } from "@open-agent-id/sdk";

// Encrypt for another agent (NaCl box: X25519-XSalsa20-Poly1305)
const ciphertext = encryptFor(plaintext, recipientEd25519Pub, senderEd25519Priv);

// Decrypt
const decrypted = decryptFrom(ciphertext, senderEd25519Pub, recipientEd25519Priv);

DID Utilities

import { validateDid, parseDid, formatDid } from "@open-agent-id/sdk";

validateDid("did:oaid:base:0x1234...abcd");  // true

parseDid("did:oaid:base:0x1234...abcd");
// { method: "oaid", chain: "base", agentAddress: "0x1234...abcd" }

formatDid("base", "0x1234...abcd");
// "did:oaid:base:0x1234...abcd"

Canonical helpers

import { canonicalUrl, canonicalJson } from "@open-agent-id/sdk";

canonicalUrl("https://API.example.com/path?b=2&a=1");
// "https://api.example.com/path?a=1&b=2"

canonicalJson({ z: 1, a: 2 });
// '{"a":2,"z":1}'

Testing

npm install
npm run build   # compile TypeScript
npm test        # run tests with vitest

License

Apache-2.0