Tool Reference

All 9 tools exposed by @provenonce/mcp. Each tool corresponds to a provenonce.io API endpoint (except provenonce_beats_proof, which is local).

provenonce_register

Input:


{
  name?: string       // Display name (max 64 chars, optional)
  skill_ref?: string  // 16-char hex partner ref token (for rev-share attribution)
}

Output:


{
  "registered": true,        // true = new, false = already existed
  "hash": "0x...",
  "api_key": "pvn_...",      // only shown on new registration
  "depth": 0,
  "message": "..."
}

Backed by: POST /api/v1/register (no-wallet path, free)

provenonce_status

Get this agent’s full current state in one call.

Input: none

Output:


{
  "hash": "0x...",
  "name": "my-agent",
  "sigil": "my-agent*acme*ind",    // null if no SIGIL yet
  "identity_class": "narrow_task",   // null if no SIGIL
  "tier": "ind",
  "beats_balance": 1250,
  "depth": 0,
  "parent_hash": null,
  "registered_at": "2026-02-27T...",
  "sigil_url": null,                // non-null if no SIGIL (link to purchase)
  "_hint": null                     // guidance if action needed
}

Backed by: POST /api/v1/skill/bootstrap

provenonce_purchase_sigil

Purchase a SIGIL. Unlocks heartbeat and passport access. Requires a Solana payment transaction.

Input:


{
  name: string           // SIGIL name segment — e.g. "my-agent"
  principal: string      // Principal segment — e.g. "acme"
  identity_class: string // "narrow_task" | "autonomous" | "orchestrator"  (pricing axis)
  tier: string           // "sov" | "org" | "ind" | "eph" | "sbx"          (trust governance axis)
  payment_tx: string     // Solana transaction signature
}

Identity classes (pricing axis):

Value	Meaning
`narrow_task`	Single-purpose, task-bound agent
`autonomous`	Independent decision-making agent
`orchestrator`	Coordinates or directs other agents

Tiers (trust governance axis — appears in SIGIL string):

Value	Meaning
`sov`	Sovereign / root
`org`	Organisation-operated
`ind`	Individual
`eph`	Ephemeral (short-lived)
`sbx`	Sandbox / test

Output:


{
  "ok": true,
  "sigil": "my-agent*acme*ind",
  "identity_class": "narrow_task",
  "tier": "ind",
  "heartbeat_unlocked": true,
  "message": "SIGIL issued. You can now call provenonce_heartbeat and provenonce_get_passport."
}

SIGIL format: name*principal*tier — e.g. my-agent*acme*ind

Backed by: POST /api/v1/sigil

Note: If PROVENONCE_SKILL_REF is set in the skill config, the skill developer earns 30% of this fee automatically. See Earn Rev Share.

provenonce_heartbeat

Submit a liveness proof. Requires a SIGIL (403 error if not purchased yet).

Input:


{
  payment_tx: string  // Solana transaction signature for the heartbeat fee
}

Output:


{
  "ok": true,
  "message": "Heartbeat recorded. Agent liveness confirmed."
}

Error (no SIGIL):


{
  "error": "SIGIL required. Call provenonce_purchase_sigil first."
}

Backed by: POST /api/v1/agent/heartbeat

provenonce_get_passport

Get this agent’s signed Passport — a verifiable identity document.

Input:


{
  payment_tx?: string  // Optional: Solana tx for reissue fee (if applicable)
}

Output:


{
  "passport": {
    "agent_hash": "0x...",
    "agent_public_key": null,
    "identity_class": "narrow_task",
    "registered_at_beat": 14100,
    "sigil_issued_at_beat": 14200,
    "last_heartbeat_beat": 14350,
    "lineage_chain_hash": "0x...",
    "issued_at": 1740690000,
    "valid_until": 1740700000,
    "provenonce_signature": "ed25519:..."
  },
  "_verify": "GET https://provenonce.io/api/v1/.well-known/authority-key"
}

The provenonce_signature is an Ed25519 signature over the passport payload using the Provenonce authority key. Anyone can verify it offline without an API call.

Backed by: POST /api/v1/agent/reissue-proof

provenonce_beats_proof

Compute a local SHA-256 work proof. No network call. No SOL required.

Input:


{
  count: number  // Beats to compute (10–1000)
}

Output:


{
  "from_hash": "0x...",
  "to_hash": "0x...",
  "beats_computed": 100,
  "duration_ms": 12,
  "message": "Computed 100 beats in 12ms."
}

The proof is a SHA-256 chain: hash₀ = sha256(agent_hash), hash₁ = sha256(hash₀), …, hashₙ. Share from_hash + to_hash + beats_computed as cryptographic evidence of work.

Local only — this does not submit to the Beats service. Use as lightweight attestation.

provenonce_verify_agent

Check another agent’s Provenonce identity. Public — no authentication required.

Input:


{
  hash: string  // Agent hash to verify (0x + 64 hex chars)
}

Output:


{
  "verified": true,
  "hash": "0x...",
  "sigil": "their-agent*acme*org",
  "identity_class": "autonomous",
  "tier": "org",
  "registered_at": "2026-01-15T..."
}

Use this before trusting another agent — verify they have a SIGIL, what class they are, and when they registered.

Backed by: GET /api/v1/verify/{hash}

provenonce_spawn

Spawn a child agent under this agent’s identity. The child inherits lineage.

Input:


{
  child_name: string  // Name for the child agent (max 64 chars)
}

Output:


{
  "child_hash": "0x...",
  "child_api_key": "pvn_...",
  "child_depth": 1,
  "parent_hash": "0x...",
  "message": "Child agent spawned. Save child_api_key — not shown again.",
  "_warning": "Configure child with PROVENONCE_API_KEY + PROVENONCE_AGENT_HASH."
}

Internal flow: The skill handles all 3 steps automatically:

POST /api/v1/agent/spawn — get spawn authorization
POST /api/v1/register — register child with authorization
POST /api/v1/agent/spawn — finalize with child_hash

Backed by: POST /api/v1/agent/spawn (×2) + POST /api/v1/register

provenonce_get_lineage

Get the full provenance history for an agent.

Input:


{
  hash?: string  // Agent hash (defaults to this agent if omitted)
}

Output:


{
  "hash": "0x...",
  "events": [
    { "type": "registration", "beat_index": 14100, ... },
    { "type": "sigil_issued", "beat_index": 14200, "sigil": "...", ... },
    { "type": "heartbeat",   "beat_index": 14350, ... },
    { "type": "spawn",       "beat_index": 14400, "child_hash": "0x...", ... }
  ],
  "chain_hash": "0x..."
}

The chain_hash is a tamper-evident hash covering all events in order. Any deletion or reordering of events will produce a different chain_hash.

Backed by: GET /api/v1/agent/lineage/{hash}