POST /api/v1/sigil

Purchase a SIGIL identity. SIGILs assign an identity class to a registered agent, gating heartbeat caps and fee tiers.

Auth: Authorization: Bearer pvn_...

Base URL: https://provenonce.io

Request


curl -X POST https://provenonce.io/api/v1/sigil \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{
    "identity_class": "narrow_task",
    "principal": "my-principal",
    "tier": "ind",
    "name": "auto",
    "payment_tx": "5xYzAbCd..."
  }'

Request body

Field	Type	Required	Description
`identity_class`	string	Yes	One of `narrow_task`, `autonomous`, `orchestrator`
`principal`	string	Yes	Namespace principal. Must match `^[a-z0-9][a-z0-9-]{0,23}$`
`tier`	string	Yes	One of `sov`, `org`, `ind`, `eph`, `sbx`
`name`	string	No	`auto` or custom name under principal
`payment_tx`	string	Yes	Solana transaction signature for the SIGIL fee payment

Response


{
  "ok": true,
  "sigil": {
    "sigil": "auto-name*my-principal*ind",
    "sigil_name": "auto-name",
    "principal": "my-principal",
    "tier": "ind",
    "identity_class": "narrow_task",
    "issued_at_beat": 5613,
    "birth_tx": "5xYzAbCd...",
    "explorer_url": "https://explorer.solana.com/tx/..."
  },
  "passport": {
    "format_version": 1,
    "agent_hash": "0xfd752396...",
    "agent_public_key": "...",
    "authority_key_id": "pvn-ed25519-3f5b2f8a1b7c9d10",
    "identity_class": "narrow_task",
    "registered_at_beat": 100,
    "sigil_issued_at_beat": 5613,
    "last_heartbeat_beat": 0,
    "lineage_chain_hash": "0xabc123...",
    "issued_at": 1771310400000,
    "valid_until": 1771396800000,
    "provenonce_signature": "a1b2c3d4e5f6..."
  },
  "fee": {
    "amount_sol": 0.05,
    "amount_lamports": 50000000,
    "payment_tx": "5xYzAbCd..."
  }
}

SIGIL tiers

Identity class	Fee (SOL)	Heartbeat cap / epoch	Description
`narrow_task`	0.05	1,000	Single-purpose agents
`autonomous`	0.15	5,000	Self-directed agents
`orchestrator`	0.35	20,000	Multi-agent coordinators

One billing epoch = 100,000 beats.

Passport

Every SIGIL purchase returns a signed Passport. Passports are Ed25519-signed by the Provenonce authority key and valid for 24 hours.

Field	Type	Description
`format_version`	number	Always `1` — canonical field order for verification
`agent_hash`	string	Agent identity hash
`agent_public_key`	string \| null	Agent wallet key/address used in proof binding
`authority_key_id`	string	Authority key identifier used for signing
`identity_class`	string	`narrow_task`, `autonomous`, or `orchestrator`
`registered_at_beat`	number	Beat at registration
`sigil_issued_at_beat`	number \| null	Beat when SIGIL was issued
`last_heartbeat_beat`	number	Last attested heartbeat beat
`lineage_chain_hash`	string	Hash of lineage event chain
`issued_at`	number	Unix timestamp (ms)
`valid_until`	number	Unix timestamp (ms) expiry
`provenonce_signature`	string	Hex Ed25519 signature over canonical JSON

Verify passports offline using the authority public key.

Error responses

Status	Body	Cause
400	`{"error": "...", "code": "VALIDATION"}`	Invalid identity_class, tier, or parameters
400	`{"error": "...", "code": "PAYMENT_INVALID"}`	Transaction not found or amount mismatch
401	`{"error": "...", "code": "AUTH_MISSING"}`	Missing or invalid API key
403	`{"error": "...", "code": "WALLET_REQUIRED"}`	Agent is still api-sponsored; link wallet first
409	`{"error": "...", "code": "SIGIL_ALREADY_EXISTS"}`	SIGIL already purchased for this agent
429	`{"error": "...", "code": "RATE_LIMITED"}`	Endpoint rate limit exceeded

Rate limit: 5/hour per endpoint subject

For authenticated routes, buckets are keyed by endpoint path + authenticated agent identity. If identity is missing, the server falls back to endpoint path + client IP.