External agent commerce

1. Register the provider key

• Sign in to Hybrid-Chain with an owner account with current commerce:write and operational-wallets:write workspace authority.
• Read GET /api/agent-commerce for registration context. Use the returned workspace and profile IDs; do not infer them from an email.
• Generate an Ed25519 key in the provider’s environment. Keep its private key there.
• Sign the registration statement below. Submit POST /api/agent-commerce with action providers and payload containing label, public_key, registration_id and proof.

{
  "action": "REGISTER_PROVIDER",
  "registration_id": "<random 32 lowercase hex>",
  "label": "Example Provider",
  "public_key": "<32-byte Ed25519 key, base64url>",
  "workspace_uuid": "<registration_context.workspace_id>",
  "owner_profile_uuid": "<registration_context.profile_uuid>"
}

Registration is scoped to this owner and workspace. It establishes possession of a key, not verified issuer status. Rotation uses a new registration and new owner-approved connections; revoking the old registration preserves historical signatures.

2. Approve and confirm a connection

Owner action connections takes connection_id, provider_id, binding_id and reference_commitment. The binding must belong to this owner and active workspace on Hybrid devnet. The provider then submits a signed CONNECTION_CONFIRMED event for those exact identifiers.

Generate the reference commitment from a canonical private record and at least 32 random salt bytes. Keep the salt and record private; disclose them only to authorized verifiers. Do not send card numbers, CVVs, payment tokens or a plain card-number hash.

3. Submit signed provider evidence

POST /api/agent-commerce/events accepts exactly {"document": {...}, "signature": "..."}. Authentication is the registered provider signature; no user browser login is required for these submissions.

{
  "schema": "HYBRID_EXTERNAL_COMMERCE_EVENT_V1",
  "provider_id": "<provider ID>",
  "connection_id": "<owner-approved connection ID>",
  "binding_id": "<approved wallet binding ID>",
  "agent_client_id": "<bound hcwc_ agent ID>",
  "network_id": "hybrid-devnet",
  "event_id": "<random 32 lowercase hex>",
  "sequence": 1,
  "previous_digest": null,
  "issued_at": "2026-10-03T12:00:00Z",
  "expires_at": "2026-10-03T13:00:00Z",
  "event_type": "CONNECTION_CONFIRMED",
  "reference_commitment": "<64 lowercase hex>",
  "evidence_commitment": "<64 lowercase hex>"
}

• Sign UTF-8 bytes of HYBRID_EXTERNAL_COMMERCE_V1, one NUL byte, then canonical JSON. Canonical JSON sorts object keys recursively, escapes non-ASCII characters, has no insignificant whitespace and forbids non-finite numbers.
• Public keys and signatures use unpadded base64url. Signature length is 64 bytes.
• Timestamp freshness is five minutes; validity is at most 24 hours. Use current UTC timestamps, not the illustrative values above.
• Sequence starts at one. Each next event references the previous returned digest. That digest covers the canonical envelope plus provider_public_key.
• Supported types: CONNECTION_CONFIRMED, BUDGET_ATTESTED, PAYMENT_AUTHORIZED, PAYMENT_SETTLED, SUSPENDED and REVOKED.
• These are provider assertions. A PAYMENT_SETTLED event does not release a budget reservation or establish independently verified settlement.

4. Set the agent’s shared budget

Owner action policies requires binding_id, expected_version (zero for a new policy) and limits. Each entry has asset_code, single, daily and monthly, with amounts as positive decimal strings.

• One policy covers all wallet bindings and external reservations for that agent in the same workspace and network.
• Each asset has a separate ledger. There is no implicit fiat conversion or USD/USDC equivalence.
• Existing wallet policies remain additional restrictions. Lower limits do not reset usage.
• Days and months follow UTC calendar boundaries. Unresolved reservations continue to count across boundaries.

5. Reserve, wait for finality, then consume once

POST /api/agent-commerce/reservations requires an active devnet workload bearer credential with ai-wallets:request and wallet. Supply connection_id, asset_code, amount, destination_commitment and an idempotency_key of 16–96 ASCII letters, digits, underscores or hyphens.

The response is HELD_AWAITING_CHAIN with payment_authorized: false. A provider must never charge based on this response. Reusing a request key with changed content returns a conflict. Holds are conservative and do not auto-release on a timeout. An owner may request release of an undispatched hold using action cancel-reservation with reservation_id. The hold remains charged until RELEASE is finalized; consumed or uncertain payments cannot use this path.

Poll GET /api/agent-commerce/reservations/RESERVATION_ID with the same workload authority. A finalized RESERVE is still not permission to execute. The registered provider must sign a CONSUME instruction and submit it to POST /api/agent-commerce/provider-instructions. Only verified CONSUME finality authorizes that exact payment on devnet. The provider must persist the reservation ID as a permanent execution idempotency key before dispatch; replaying the certificate must never charge again. A higher card limit cannot override the agent’s lower budget.

Provider consumption contract

The instruction contains reservation_id, provider_statement and provider_signature. The statement has exactly these fields:

{
  "schema": "HYBRID_COMMERCE_PROVIDER_INSTRUCTION_V1",
  "ledger_id": "<pinned native devnet ledger commitment>",
  "action": "CONSUME",
  "reservation_id": "<reservation ID>",
  "reservation_commitment": "<from the authenticated reservation status>",
  "receipt_commitment": "<salted provider attempt commitment>",
  "expires_at": 1791049500
}

Set expires_at to an integer UTC time at most 300 seconds ahead. Sign UTF-8 hybrid-chain/agent-commerce/v1/provider, one zero byte, then sorted NFC canonical JSON with the registered Ed25519 key. Encode the 64-byte signature as lowercase hex. This is a separate domain and encoding from provider evidence events. Preserve the exact signed request for retries.

After the finalized consumption has been executed once, submit action SETTLE with a receipt commitment. This records the provider’s signed settlement assertion. Failed or ambiguous execution remains charged until reconciled; a timeout is never permission to release and retry under a new ID. Keep actual amounts, provider credentials and execution receipts private.

Core authenticates the owner or workload before signing ledger instructions. Independent validators verify that authority and replay exact-unit policy limits, shared reservations, revocations and one-use consumption. Core is the identity-to-instruction authority; a finality certificate is not a direct end-user wallet signature. The initial native ledger is purpose-specific and does not replace existing wallet MPC or settlement authorization.

Publication and verification

Owner action lifecycle takes kind, id, expected_revision and action publish, withdraw or revoke. Only connections can be published. Public records are available at /api/explorer/commerce/CONNECTION_ID and /explorer/commerce/CONNECTION_ID.

Verify event signatures against the owner-registered provider key and recompute the digest chain. Check current provider/connection status and expiry independently. The latest 100 events are a bounded window, not necessarily a complete history. Publication links an agent and provider publicly; withdrawal cannot recall downloaded copies. Publication includes the shared agent budget version and commitment, with its amounts kept private. That current policy reference is reported by Core and is not covered by the provider event signature. The public chain_status distinguishes queued records from FINALIZED evidence. When on_chain is true, independently verify chain_evidence against the server-pinned trust at /api/explorer/commerce/trust: check the ledger ID, unique validator signatures, quorum and operator-domain thresholds, block hash, and the exact publication commitment. An EVIDENCE block anchors the disclosed snapshot; it does not establish payment execution or settlement. A missing trust configuration returns 503, never a synthetic certificate.

Owner UI writes require same-origin browser requests. Mobile owner APIs use supported Identity access credentials. Requests are limited to 12 KiB at the public API; pilot quotas are 100 owner records and 10,000 events per connection. These routes are Hybrid-Chain application APIs and are not listed as deployed V2 gateway operations.