Counterparties and economic context

The ledger records amounts, while counterparties and metadata record meaning: who is on the other side and why the operation happened. This layer turns raw movements of funds into business events you can build reports on.

Three layers of context

Economic context is made up of three layers, which are easy to confuse:

A counterparty is a set of addresses

A counterparty is a named entity with linked addresses. The name is unique within a Vault, and each address belongs to at most one counterparty; otherwise, matching would be ambiguous. Address networks are validated against the Networks registry.

• POST /api/v1/vaults/{code}/counterparties creates a counterparty (optionally with addresses right away).
• POST /api/v1/vaults/{code}/counterparties/{id}/addresses adds an address.
• GET /api/v1/vaults/{code}/counterparties returns a list with the search (substring in the name) and kind (for example, exchange) filters.

curl -X POST "[BASE_URL]/api/v1/vaults/acme-otc/counterparties" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Exchange",
    "kind": "exchange",
    "addresses": [{ "network": "tron", "address": "TQ2m...p4rX" }]
  }'

await fetch("[BASE_URL]/api/v1/vaults/acme-otc/counterparties", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "ACME Exchange",
    kind: "exchange",
    addresses: [{ network: "tron", address: "TQ2m...p4rX" }],
  }),
});

requests.post(
    "[BASE_URL]/api/v1/vaults/acme-otc/counterparties",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={
        "name": "ACME Exchange",
        "kind": "exchange",
        "addresses": [{"network": "tron", "address": "TQ2m...p4rX"}],
    },
)

Auto-matching and retroactive matching

When an operation goes to or from a known address, it's automatically linked to the counterparty, so there's no need to tag it manually. And if an address is added later, a retroactive match kicks in: existing operations involving that address are matched to the counterparty after the fact, and the classification history is preserved.

Counterparty groups

Counterparties can be grouped, for example, by type or jurisdiction:

• POST /api/v1/vaults/{code}/counterparty-groups creates a group (members are added separately). This mutation is gated by the counterparty_group_create policy: if approval is required, an approval request is returned.

Archiving: history is never lost

Counterparties aren't deleted; they're archived:

• POST /api/v1/vaults/{code}/counterparties/{id}/archive with archived=true: the counterparty stops matching new operations and can't be used for new transfers, but its history is preserved; false restores it. Gated by the counterparty_archive policy.

Operation categories

Categories are a configurable, versioned catalog used to build reports and filters:

• GET /api/v1/vaults/{code}/operation-categories returns the Vault's category list. The schema is visible to every member (it's used to build categoryKey, groupByField, and metricField for the report builder); viewScope restricts access to the values on operations, not to the schema itself.

A category can have its own approvers (POST / DELETE /api/v1/vaults/{code}/operation-categories/{id}/approvers), so operations in a certain category can require approval from designated people (see Approvals).

Operation metadata

Metadata attaches business context to an operation. GET / PATCH /api/v1/vaults/{code}/operations/{type}/{id}/metadata upserts flat fields; each change increments version.

curl -X PATCH "[BASE_URL]/api/v1/vaults/acme-otc/operations/transfer/OPERATION_ID/metadata" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paymentPurpose": "Invoice payment", "category": "settlement", "invoiceId": "INV-2026-0042" }'

await fetch("[BASE_URL]/api/v1/vaults/acme-otc/operations/transfer/OPERATION_ID/metadata", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    paymentPurpose: "Invoice payment",
    category: "settlement",
    invoiceId: "INV-2026-0042",
  }),
});

requests.patch(
    "[BASE_URL]/api/v1/vaults/acme-otc/operations/transfer/OPERATION_ID/metadata",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={
        "paymentPurpose": "Invoice payment",
        "category": "settlement",
        "invoiceId": "INV-2026-0042",
    },
)

Operation relations

Operations can be explicitly linked to each other to reflect an economic relationship:

• POST /api/v1/vaults/{code}/operation-relations creates a relation. An opposite payment is not automatically treated as a refund; the link must be set explicitly.

For how these relations work with the ledger's immutability, see Ledger (double-entry).

Terms

Next steps