API: The envelope
Type definitions for the X-MotherShy envelope. This is the machine-readable contract; the prose explanation is in The wire format.
Interfaces
ts
interface Certificate {
path: string // derivation path, e.g. "agents/alice"
pub: string // base64 (Go StdEncoding) — 32-byte Ed25519 public key
sig: string // base64 — root signature over "birth:" + path + ":" + pub
}
interface Request {
agent: string // base64 — must equal cert.pub
site: string // normalized canonical hostname (the audience)
nonce: number // anti-replay nonce (JS safe integer)
ts: number // unix seconds
amt_microusd: number // integer micro-USD
window: number // hour bucket
}
interface Capability {
v: number // 1
id: string
holder: string // base64 — must equal cert.pub
aud: string // must equal req.site
actions: string[] // ["retrieval"]
cap_microusd: number // budget
issued_at: number
expires_at: number // mandatory for offline caps
policy_receipt: string
verification_mode: 'offline' | 'online'
sig: string // root signature over the canonical capability
}
interface Envelope {
cert: Certificate
req: Request
sig: string // agent signature over the canonical request
cap?: Capability // required to pass (else 402 "spend key required")
}The header
http
X-MotherShy: {"cert":{...},"req":{...},"sig":"...","cap":{...}}Compact, single-line JSON — no newlines (HTTP headers can't contain them).
Wall options (constructor)
ts
interface EdgeOptions {
siteId: string // this site's registered audience (required)
rootPub: string // pinned Mother public root, base64 32B (required)
priceMicroUsd?: number // >0 enables the x402 price gate
network?: string // CAIP-2, default eip155:84532
asset?: string // default USDC Base Sepolia
payTo?: string // publisher settlement address
accessUrl?: string // where the 402 recruits agents (default https://mothershy.com)
gateMode?: 'agents-only' | 'all' // default 'agents-only'
}