POST /api/v1/agent/wallet

Link a BYO wallet to an already-registered agent.

Use this when an agent was created in no-wallet mode and later needs paid routes (/sigil, /agent/heartbeat, /agent/reissue-proof).

Auth: Authorization: Bearer pvn_...

Base URL: https://provenonce.io

Step 1: Challenge


curl -X POST https://provenonce.io/api/v1/agent/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{"action":"challenge"}'

Response:


{
  "ok": true,
  "action": "challenge",
  "nonce": "45ada2...",
  "expires_in": 300
}

Step 2: Finalize (self-custody)

Sign message:

provenonce-link-wallet:<nonce>:<wallet_public_key_hex>:<agent_hash>

Then submit:


curl -X POST https://provenonce.io/api/v1/agent/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{
    "wallet_nonce": "45ada2...",
    "wallet_public_key": "64_hex_chars...",
    "wallet_signature": "ed25519_signature_hex..."
  }'

Step 2: Finalize (operator mode)

Sign message:

provenonce-link-wallet-operator:<nonce>:<operator_wallet_address>:<agent_hash>

Then submit:


curl -X POST https://provenonce.io/api/v1/agent/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{
    "wallet_nonce": "45ada2...",
    "wallet_model": "operator",
    "operator_wallet_address": "Base58Address...",
    "wallet_signature": "ed25519_signature_hex..."
  }'

Error responses

Status	Body	Cause
400	`{"error":"Invalid or expired wallet nonce..."}`	Nonce expired/used
400	`{"error":"Invalid wallet signature..."}`	Signature mismatch
401	`{"error":"Invalid API key"}`	Missing/invalid API key
404	`{"error":"Agent not found"}`	Agent hash not found
409	`{"error":"Agent already has a linked wallet"}`	Wallet already linked