oc·docs
live · mainnetoc · docs
specs · api · guides
docs / overview

OC Agent

Every agent gets a Bitcoin address. Every action, signed. OC Agent is the delegation-authority primitive in the OrangeCheck family: a principal grants an autonomous agent — a script, a bot, a pipeline, an LLM — scoped action rights bound to the principal's Bitcoin identity. Every action the agent takes is non-repudiable, offline-verifiable, and contained by scope + time. No OAuth, no custodial tokens, no trusted issuer.

What it proves

A valid Agent action envelope proves three things cryptographically:

  1. The action was issued under a valid delegation. The delegation is BIP-322-signed by the principal's Bitcoin address.
  2. The action is within the granted scope. Scopes are declarative strings like lock:seal(recipient=bc1qalice) or ln:send(max_sats<=1000,node=03abc…); the verifier matches the action against the granted scope set deterministically.
  3. The delegation is not revoked and not expired. Revocation is advertised via Nostr kind-30085 under the d-tag prefix oc-agent-rev:<id>; expiry is a plain timestamp in the delegation record.

And optionally, with an Attest reference:

  1. The principal held N sats for N days at the moment of delegation. A stake-at-signing signal that verifiers can re-resolve from live chain state.

Who this is for

  • CI / release pipelines that sign artifacts, stamps, or envelopes on a principal's behalf without handing the pipeline the Bitcoin key.
  • Autonomous trading / LN routing bots that need a hard ceiling on blast radius — max_sats<=N, recipient in {…}, max_actions_per_minute<=M.
  • Social / Nostr bots that post under a human's identity on a revocable, scoped leash.
  • LLM agents signing calls to downstream tools where the operator wants a tamper-evident audit trail of "what the agent did, under whose authority."

Who this is NOT for

  • Transferring the principal's Bitcoin key. The principal's key never leaves their wallet. The agent holds only the delegation record and its own keypair.
  • Transitive re-delegation. An agent cannot issue sub-delegations in v0. If you need an agent to delegate further, re-mint a delegation from the principal that targets the sub-agent.
  • Replacing centralized IAM. OAuth + role-based access is fine when there's a central operator. OC Agent is the answer when the identity root is a Bitcoin address, not an issuer.

Section contents

  • Why OC Agent — what breaks without it, why Bitcoin-bound delegation, what the alternatives can't do.
  • Quickstart — mint a delegation, sign an action, verify it downstream. Five minutes.
  • Protocol walkthrough — the envelopes (delegation, action, revocation, sub-delegation), the canonical flows, diagrams.
  • Sub-delegation (v1.1) — chained authority. An agent grants a narrower slice of its delegated rights to another agent.
  • Private scope (v1.2) — confidential mode for the scope list. The principal seals scopes via OC Lock to the agent + named verifiers; public observers see ciphertext.
  • Scope grammar — BNF, sub-scope containment, constraint semantics, the 8 MVP scopes.
  • Security posture — revocation timing, blast radius, what scopes cannot constrain.
  • Specification — normative rules; the reference impls in oc-packages are required to pass its conformance vectors.

Packages

  • @orangecheck/agent-core — canonical delegation + action envelope format, scope parser, verifier.
  • @orangecheck/agent-signer — helpers for signing delegations (principal) and actions (agent).
  • @orangecheck/agent-cli — oc-agent shell for minting / revoking / verifying envelopes.
  • @orangecheck/agent-mcp — Model Context Protocol bridge so LLM toolchains can produce agent-signed tool calls directly.

See SDK overview.

Shared ecosystem concepts

Agent inherits the same plumbing every OrangeCheck protocol uses:

  • Canonical message format — the delegation record is a canonical message.
  • BIP-322 signing — the principal's delegation signature.
  • Nostr publication — delegations live on kind-30083 (co-claimed with OC Stamp under disjoint d-tag prefixes oc-agent-del: vs oc-stamp:), agent-actions on kind-30084 (claimed exclusively by OC Agent — they reuse OC Stamp's envelope structure but on a distinct Nostr kind), revocations on kind-30085, sub-delegations (v1.1) on kind-30086.
  • Conformance vectors — the cross-impl test suite.
  • Security model — shared threat framework.

Spec + implementation

  • Normative spec: oc-agent-protocol/SPEC.md
  • Reference impls: @orangecheck/agent-core, agent-signer, agent-cli, agent-mcp in oc-packages
  • Reference site: agent.ochk.io — sign delegations at /app, consume them as the agent at /agent, verify any envelope at /inspect.
  • Worked integrations: oc-agent-examples — a fork-ready mcp-wrap CLI (client side) and verifying-mcp-server (server side) that together demonstrate the full authority loop without the agent's private key ever leaving its wallet.