Event schema

An Agent Payment Event (APE) is the single format HalvorAI uses for every rail. You map your rail’s payload into it, sign it, and send it. For how the pieces fit, see events.

Top-level fields

Field	Required	Purpose
ape_version	Yes	The schema version, currently 0.1.
id	Yes	An evt_ id. Also the idempotency key.
type	Yes	payment.requested, payment.authorized, payment.settled, payment.failed, payment.refunded or payment.disputed.
occurred_at	Yes	When it happened, UTC, RFC 3339 with milliseconds.
environment	Yes	test or live.
source	Yes	Which producer signed this event.
agent	Yes	The agent that acted.
owner	Yes	The party the agent acts for.
payment	Yes	The rail, amount and status.
payee	Yes	Who was paid.
instruction	No	A hash of the instruction, and an optional redacted summary. Instruction text is never sent.
instrument	No	The card, token or wallet used.
evidence	No	Network proofs carried verbatim. See evidence.
related	No	Links to earlier events, such as the authorization a settlement follows.
labels	No	Free-form key and value tags.

Rules that matter

• Money is an integer. Minor units with an ISO 4217 currency, or atomic units with a CAIP-2 asset. Amounts travel as decimal strings. Never floats.
• Rails are card, stripe, x402, mpp, stablecoin and bank_transfer, each with its own allowed rail_ref keys.
• Signing. The event is signed as a detached EdDSA JWS over its RFC 8785 canonical form, and sent as { event, sig }.
• No card numbers. An event with a card number is rejected with pan_detected.

Get the schema

The JSON Schema and worked examples are published with the project under schema/:

• ape-v0.1.schema.json is the JSON Schema (draft 2020-12).
• examples/ holds a Stripe Issuing authorization carrying an AP2 mandate, a failed Stripe payment, and a settled x402 payment.

You can check an event without sending it: POST /v1/events/validate, or halvor validate in the CLI.

Versioning

Minor versions only add optional fields. Until 1.0 a minor version may still break compatibility, and the changelog will say so.