Agents, owners and payees
You never create agents, owners or payees by hand. HalvorAI builds them from the events you send, and keeps them up to date as new events arrive.
Agents
Section titled “Agents”An agent is whatever acts and pays on someone’s behalf: a language-model agent, a script, a purchasing bot.
You choose its id, and it should be stable across runs. HalvorAI creates one agent per distinct agent.id.
An agent record holds the name, framework and version you sent, a key thumbprint if it has a signing key, its first and last activity, and 30-day activity figures: settled payments, spend in US dollars, and the rails it used.
The only fields you can edit are a label and notes, through PATCH /v1/agents/{id}. Everything else comes from
events, so what an auditor sees matches what actually happened. Each edit is recorded in the audit log with the old and
new value.
If an event arrives without an agent, HalvorAI stores it with the agent unattributed and counts it against your
attribution coverage. See attribution.
Owners
Section titled “Owners”An owner is the person or business an agent acts for. Each owner has an id you choose, a type (person or
business), and optionally a display name, a country and a kyc_ref.
One agent can be linked to one owner at a time. The most recent event decides.
Payees
Section titled “Payees”A payee is whoever received the payment. HalvorAI groups payees by a normalized key so the same recipient is one payee however it appears:
| If the event has | The payee key is |
|---|---|
| A wallet | wallet:<network>:<address>. Ethereum-style addresses are lowercased. Other chains compare exactly. |
| An id | merchant:<id> |
| Only a name | name:<normalized name>|<country>. Accents, punctuation and case are removed. |
For each agent and payee pair HalvorAI keeps the first time they met, a count of settled payments and the total in
US dollars. The first payment from an agent to a new payee is what the new_payee detector watches for.
Newest information wins
Section titled “Newest information wins”If the same agent or payee appears with different details, the details from the newest event are kept. A late or backfilled event never overwrites newer information, and a missing field never erases a known one.
Reading them
Section titled “Reading them”GET /v1/agents, GET /v1/owners and GET /v1/payees list them, and the {id} variants fetch one. See
read your data.