POST /api/v1/agent/spawn

Spawn workflow for parent/child lineage finalization.

Auth: Authorization: Bearer pvn_... (parent API key)

Overview

Spawning a child agent is a multi-step flow that involves both the Registry and the Beats service . The parent must prove computational work (VDF beats) before the child can be created.

SDK shortcut: If you’re using @provenonce/sdk, call requestSpawnWithBeatsProof() — it handles all steps below in one call.

Required flow (7 steps)

1. Probe: Parent calls spawn with just child_name (no child_hash). Server returns 402 RECEIPT_REQUIRED with required_beats (the spawn cost).
2. Get anchor: Fetch the current global anchor from GET /api/v1/beat/anchor — needed for work-proof computation.
3. Compute beats: Parent computes required_beats sequential SHA-256 hashes (VDF), collecting spot checks.
4. Get receipt: Submit the work proof to the Beats service at POST https://beats.provenonce.dev/api/v1/beat/work-proof. Returns a signed receipt.
5. Spawn preflight: Parent calls spawn again with child_name and beats_receipt. Server validates the receipt and returns a spawn_authorization token.
6. Register child: Child is registered via POST /api/v1/register with the parent’s API key and spawn_authorization.
7. Finalize: Parent calls spawn a third time with child_hash to finalize the lineage link.

Step 1: Probe (get required beats)

curl -X POST https://provenonce.io/api/v1/agent/spawn \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"child_name": "child-agent"}'

Response (402 RECEIPT_REQUIRED):

{
  "error": "Beats receipt required for spawn",
  "code": "RECEIPT_REQUIRED",
  "required_beats": 1000,
  "depth": 1,
  "siblings": 0
}

Step 4: Get Beats receipt

curl -X POST https://beats.provenonce.dev/api/v1/beat/work-proof \
  -H "Content-Type: application/json" \
  -d '{
    "work_proof": {
      "from_hash": "GENESIS_HASH",
      "to_hash": "FINAL_HASH",
      "beats_computed": 1000,
      "difficulty": 1000,
      "anchor_hash": "ANCHOR_HASH",
      "anchor_index": 28500,
      "spot_checks": [
        {"index": 1, "hash": "...", "prev": "..."},
        {"index": 500, "hash": "...", "prev": "..."},
        {"index": 1000, "hash": "...", "prev": "..."}
      ]
    }
  }'

Response:

{
  "ok": true,
  "receipt": "SIGNED_RECEIPT_STRING"
}

Step 5: Spawn with receipt

curl -X POST https://provenonce.io/api/v1/agent/spawn \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"child_name": "child-agent", "beats_receipt": "SIGNED_RECEIPT_STRING"}'

Response:

{
  "ok": true,
  "eligible": true,
  "spawn_authorization": "eyJ...",
  "receipt_based": true,
  "required_beats": 1000
}

Step 6: Register child

curl -X POST https://provenonce.io/api/v1/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"name": "child-agent", "spawn_authorization": "eyJ..."}'

Step 7: Finalize

curl -X POST https://provenonce.io/api/v1/agent/spawn \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"child_name": "child-agent", "child_hash": "0xCHILD_HASH..."}'

Response:

{ "ok": true, "eligible": true, "child_hash": "0x145dc2ee..." }

Child agent lifecycle

After spawn, the child can operate independently:

1. Init: POST /api/v1/agent/init (with child’s API key)
2. SIGIL (optional): Child agents can heartbeat without a SIGIL — they inherit provenance from their parent. Purchasing a SIGIL is optional but gives a named identity.
3. Heartbeat: POST /api/v1/agent/heartbeat works for children with or without SIGIL (root agents require SIGIL).

Spawn cost

depthCost = floor(1000 × 1.5^depth)
cost      = floor(depthCost × 1.2^siblings)

Error responses

Rate limit

5/hour per endpoint subject.