Tool Reference

All 11 tools exposed by @provenonce/mcp. Each tool maps to a provenonce.io API endpoint (except provenonce_beats_proof, which computes locally then submits to the Beats service).

Payment flow: For paid tools (SIGIL, heartbeat, passport), call without payment_tx to receive payment instructions (fee amount + address). The agent pays using its own wallet, then calls again with the transaction signature.

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.

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 tx signature. If omitted, returns payment instructions.
}

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. Root agents (depth 0) require a SIGIL; child agents (depth > 0) can heartbeat without one.

Input:


{
  payment_tx?: string  // Solana tx signature. If omitted, returns payment instructions.
}

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": "Verify at: GET https://provenonce.io/.well-known/provenonce-authority.json for the authority public 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 sequential SHA-256 work proof and submit to the Beats service for a signed receipt. No SOL required.

Input:


{
  count: number       // Beats to compute (10–10,000)
  difficulty?: number // Hash iterations per beat (default 1000, min 100, max 5000)
}

Output:


{
  "from_hash": "0x...",
  "to_hash": "0x...",
  "beats_computed": 1050,
  "duration_ms": 340,
  "difficulty": 1000,
  "receipt": {
    "type": "work_proof",
    "beats_verified": 1050,
    "difficulty": 1000,
    "anchor_index": 14350,
    "anchor_hash": "0x...",
    "from_hash": "0x...",
    "to_hash": "0x...",
    "utc": "2026-03-04T...",
    "signature": "ed25519:..."
  },
  "message": "Computed 1050 beats at difficulty 1000 in 340ms. Signed receipt obtained."
}

The receipt is a signed attestation from the Beats service that can be used for spawn authorization and resync. If the Beats service is unavailable, the local proof is still returned but without a signed receipt.

Backed by: Local computation + POST https://beats.provenonce.dev/api/v1/beat/work-proof

provenonce_submit_beats

Compute VDF beats and submit to the Registry to credit this agent’s lifetime beat count. Unlike provenonce_beats_proof (which gets a receipt for spawn/resync), this extends the agent’s persistent beat chain.

Input:


{
  count?: number  // Beats to compute (default 100, min 10, max 2000)
}

Output:


{
  "beats_accepted": 100,
  "total_beats": 1250,
  "duration_ms": 340,
  "difficulty": 1000,
  "message": "Submitted 100 beats to Registry in 340ms. Total lifetime beats: 1250."
}

Backed by: POST /api/v1/agent/beats/submit

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. The full response includes additional fields (standing, beat_state, liveness, lineage) — see GET /api/v1/verify/:hash for the complete shape.

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}

provenonce_batch_heartbeat

Submit heartbeats for multiple child agents in a single call. Requires active sponsorships for each child (see RFC-021).

Input:


{
  children: string[]     // Array of child agent hashes (max 20)
  payment_tx?: string    // Solana tx signature covering total fee. If omitted, returns payment instructions.
}

Output:


{
  "ok": true,
  "summary": {
    "total": 3,
    "succeeded": 3,
    "failed": 0
  },
  "results": [
    { "hash": "0x...", "ok": true },
    { "hash": "0x...", "ok": true },
    { "hash": "0x...", "ok": true }
  ],
  "message": "Batch heartbeat: 3/3 succeeded."
}

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