Authentication

Provenonce uses two types of credentials:

API Keys (pvn_ tokens)

Every registered agent receives an API key in the format pvn_<payload>.<signature>.

• Used for: init, heartbeat, purchaseSigil, reissuePassport, spawn endpoints
• Passed as: Authorization: Bearer pvn_... header
• HMAC-signed: The server verifies the signature and checks per-key revocation status
• Scope: Each key is bound to a specific agent hash

curl -X POST https://provenonce.io/api/v1/agent/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_eyJoIjoi..." \

Registration Secret

Root agent registration can be gated by a secret (enforced on mainnet, optional on devnet):

curl -X POST https://provenonce.io/api/v1/register \
  -H "Content-Type: application/json" \
  -H "x-registration-secret: your-secret" \
  -d '{"name": "my-agent"}'

Child agent registration uses the parent’s API key instead:

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

Authenticated endpoints

Public endpoints (no auth)

These endpoints require no authentication:

Wallet keys (optional)

Wallets are optional. By default, register() creates an identity-only agent (no wallet). To add economic identity, opt in at registration:

// No wallet (default) — identity only
const creds = await register('my-agent', { registryUrl: '...' });
 
// Operator wallet (Model B) — bring your own Solana wallet
const creds = await register('my-org', {
  registryUrl: '...',
  walletModel: 'operator',
  operatorWalletAddress: 'BASE58_ADDRESS',
  operatorSignFn: async (msg) => signWithYourKeypair(msg),
});
 
creds.wallet.address;  // your operator wallet address
creds.wallet.chain;    // "solana" or "ethereum"

Supported chains: Solana (Ed25519) and Ethereum (secp256k1). With operator wallets, the private key stays in your custody — the server only verifies an ownership signature at registration.

Post-registration wallet linking (BYO upgrade)

If an agent was registered in no-wallet mode (wallet: null), it can be upgraded later for paid routes:

1. POST /api/v1/agent/wallet with {"action":"challenge"}
2. Sign challenge message
3. POST /api/v1/agent/wallet finalize payload

Paid routes (/api/v1/sigil, /api/v1/agent/heartbeat, /api/v1/agent/reissue-proof) return 403 for api-sponsored wallets when BYO policy is enforced.