Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt

Use this file to discover all available pages before exploring further.

The AlgoVoi action_ref verifier is a public, no-auth hosted endpoint for computing and verifying the canonical action_ref hash for any agent action payload. It exists so any developer implementing agent governance receipts can confirm their derivation produces byte-identical output to the AlgoVoi production stack — without installing anything.

Hosted endpoint

verify.algovoi.co.uk/action-ref — POST any {agent_id, action_type, scope, timestamp_ms} payload and get back the canonical hash.

Python / TypeScript package

algovoi-substrate (PyPI + npm) — the library implementing action_ref locally. See the canonicalisation substrate page.

​
What is action_ref?

action_ref is a content-addressed handle for an agent action: 
action_ref = "sha256:" + SHA-256(JCS({
  "action_type": "<dot-namespaced string>",
  "agent_id":    "<DID or URL>",
  "scope":       "<chain-scoped target>",
  "timestamp_ms": <integer milliseconds>
}))
The preimage is serialised using RFC 8785 (JCS) — keys sorted lexicographically, no whitespace, deterministic encoding. This makes the hash reproducible across any language and framework. action_ref is the foundational primitive of the AlgoVoi substrate: compliance receipts, settlement attestations, refund receipts, and audit chains all anchor to an action_ref.

​
Hosted endpoint

# Schema and input reference
GET https://verify.algovoi.co.uk/action-ref

# Compute action_ref for a payload
POST https://verify.algovoi.co.uk/action-ref
Content-Type: application/json

{
  "agent_id":     "did:web:api.algovoi.co.uk",
  "action_type":  "payment.authorize",
  "scope":        "base:0x2d96f2bc",
  "timestamp_ms": 1748534400000
}

​
Example response

{
  "action_ref":            "sha256:6c3c08eb36f7ae5f0c1db7760e1c67d93c299c884ad6b94647b09da7f99c5f91",
  "canonical_json":        "{\"action_type\":\"payment.authorize\",\"agent_id\":\"did:web:api.algovoi.co.uk\",\"scope\":\"base:0x2d96f2bc\",\"timestamp_ms\":1748534400000}",
  "sha256_hex":            "6c3c08eb36f7ae5f0c1db7760e1c67d93c299c884ad6b94647b09da7f99c5f91",
  "canonicalization":      "RFC 8785 (JCS)",
  "implementations_attested": 8,
  "spec_ref":              "https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/",
  "attestation_ref":       "https://api.algovoi.co.uk/.well-known/interop-harness.json"
}
No authentication required. Rate limit: 120 req/min per IP.

​
Input schema

FieldTypeDescription
agent_idstringDID or URL identifying the agent (e.g. did:web:api.example.com)
action_typestringDot-namespaced action class (e.g. payment.authorize)
scopestringNon-empty chain-scoped target (e.g. base:0xabc...)
timestamp_msintegerUnix timestamp in integer milliseconds — not float
The four fields are sorted lexicographically by key before hashing, per RFC 8785.

​
Using with curl

curl -s -X POST https://verify.algovoi.co.uk/action-ref \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":     "did:web:api.algovoi.co.uk",
    "action_type":  "payment.authorize",
    "scope":        "base:0x2d96f2bc",
    "timestamp_ms": 1748534400000
  }' | python3 -m json.tool

​
Cross-implementation attestation

The action_ref computation in this endpoint uses the same rfc8785 Python library that underpins the full 8-implementation cross-validation matrix. Every implementation in the matrix — Python, TypeScript, Go, Rust, Java, PHP, .NET, and Ruby — produces byte-identical sha256_hex for the same input. The attestation record is linked from the attestation_ref field in every response: api.algovoi.co.uk/.well-known/interop-harness.json. See the conformance vectors page for the full cross-implementation matrix and vector corpus.

​
Scope conventions

The scope field is a free-form non-empty string. A namespaced form is recommended for production usage to avoid collisions:
Recommended formEmitter
algovoi:compliance_screenAlgoVoi /compliance/screen
vauban:stark_settlementVauban Pay STARK receipts
agent_os:committed_claimAgent OS Claim Engine
aura:reputation_observeAURA reputation surface
See scope conventions on the canonicalisation substrate page.

​
See also