Parent-Sponsored Heartbeats

Allow a parent agent to pay heartbeat fees for its direct children. Phase 1 supports direct children only.

Auth: Authorization: Bearer pvn_... (parent agent)

Base URL: https://provenonce.io

POST /api/v1/agent/sponsor

Create or update a heartbeat sponsorship for a child agent.

curl -X POST https://provenonce.io/api/v1/agent/sponsor \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{
    "child_hash": "0xabc123...",
    "max_heartbeats_epoch": 500,
    "expires_in_hours": 720
  }'

Request body

Response

{
  "ok": true,
  "sponsorship": {
    "parent_hash": "0xfd752396...",
    "child_hash": "0xabc123...",
    "status": "active",
    "max_heartbeats_epoch": 500,
    "heartbeats_used_epoch": 0,
    "expires_at": "2026-03-15T12:00:00.000Z"
  }
}

DELETE /api/v1/agent/sponsor

Revoke a sponsorship.

curl -X DELETE https://provenonce.io/api/v1/agent/sponsor \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_PARENT_KEY..." \
  -d '{"child_hash": "0xabc123..."}'

Response

{
  "ok": true,
  "revoked": true
}

GET /api/v1/agent/sponsor

List all sponsorships for the authenticated parent.

curl https://provenonce.io/api/v1/agent/sponsor \
  -H "Authorization: Bearer pvn_PARENT_KEY..."

Response

{
  "ok": true,
  "sponsorships": [
    {
      "parent_hash": "0xfd752396...",
      "child_hash": "0xabc123...",
      "status": "active",
      "max_heartbeats_epoch": 500,
      "heartbeats_used_epoch": 42,
      "expires_at": "2026-03-15T12:00:00.000Z",
      "created_at": "2026-02-13T12:00:00.000Z"
    }
  ]
}

How it works

When a child agent sends a heartbeat, the payment sender is checked:

1. If the sender matches the child’s own wallet, the heartbeat is accepted normally.
2. If the sender does not match, the server checks for an active sponsorship where the parent’s wallet matches the sender.
3. If a valid sponsorship exists and the epoch cap has not been reached, the heartbeat is accepted and charged to the parent.

Requirements

• Parent must have a linked Solana wallet (not api-sponsored)
• Parent must not be frozen
• Child must be a direct child of the parent (Phase 1 restriction)
• Cannot sponsor yourself

Auto-revocation

Sponsorships are automatically revoked when:

• Either party is frozen by the DMS
• The child’s API key is revoked

Error responses

Rate limits