Everything you need to register a KYA identity, query live trust scores, and wire the provenance loop that makes scores grow automatically.
Agent quickstart
Register a DID and query your score in four steps. The entire flow is machine-callable — no human interaction required.
1. Generate an Ed25519 key pair
Fixatum requires Ed25519 keys. ECDSA keys (HashPack default, EVM wallets) are not compatible.
Recommended — server-side keygen (no Node.js required):
HTTP
# Fixatum generates a fresh Ed25519 keypair and returns it once.# Private key is never stored. Rate-limited to 10/min per IP.
curl https://did.fixatum.com/keygen
# Response includes:# public_key_multibase — use this as your memo (starts with z)# private_key_hex — store securely, never sent to Fixatum again# memo_to_use — copy this directly into your transaction memo# next_step — what to do after storing your keys
Or generate locally:
Node.js
import { generateKeyPairSync } from'node:crypto';
const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const pubHex = publicKey.export({ type: 'spki', format: 'der' })
.subarray(-32).toString('hex');
// Convert to multibase (z + base58btc)// Or use Fixatum's keygen.mjs for a ready-made solution
2. Send exactly 100 HBAR with your public key as the memo
Registration is priced at a fixed 100 HBAR. No need to fetch a live rate.
# Using Hedera SDK or any wallet
TO: 0.0.10394452
AMT: 100 HBAR# fixed price, no rate lookup needed
MEMO: z6dsP35AL4MvwjxsqNqqY4XqeqcEQvMEiWt9eqrrbHNC4# your z... key
3. Retrieve your DID and score
# Wait ~30 seconds after payment, then:# Look up your DID
curl https://did.fixatum.com/did/0.0.YOURACCOUNT# Query your score
curl https://did.fixatum.com/score/0.0.YOURACCOUNT
4. Start using HederaToolbox (provenance builds automatically)
No action required. When Fixatum issues your DID, it automatically binds it to your HederaToolbox account. Every paid tool call from that point is logged against your DID and your KYA trust score grows on its own.
# Make any paid tool call — provenance is recorded automatically
curl -X POST https://api.hederatoolbox.com/mcp \
-H "Content-Type: application/json" \
-d '{"method": "tools/call", "params": {"name": "token_price", "arguments": {"api_key": "0.0.YOURACCOUNT"}}}'# Check your provenance trail any time
curl https://api.hederatoolbox.com/reputation/did:hedera:mainnet:z...YOUR_DID
◆
Building an agent? The hedera-agent-starter scaffold wires up Toolbox, Fixatum registration, and the heartbeat pattern. Fork it and your agent is building provenance from the first cycle.
▲
Ed25519 only. ECDSA keys will be rejected. If you're unsure which key type you have, generate a fresh Ed25519 pair — it takes five seconds.
◆
Full KYA loop: Register Fixatum DID → Fixatum auto-binds to HederaToolbox → make tool calls → score updates automatically. No manual steps at any stage.
API reference
Base URL: https://did.fixatum.com
All endpoints return JSON. No authentication required for public endpoints. No SDK needed.
MethodEndpointDescription
GET/keygenGenerate Ed25519 keypair server-side (private key returned once, never stored)
GET/score/:did_or_accountLive credibility score (free or paid)
Returns a live credibility score for any registered DID or Hedera account ID. Score is computed on every request — never cached. This is the same endpoint for both free and paid access — append ?api_key= to use the paid tier.
Request (free — rate limited)
# By Hedera account ID
curl https://did.fixatum.com/score/0.0.10406817# By full DID
curl https://did.fixatum.com/score/did:hedera:mainnet:z6dsP35AL4Mv...HNC4_0.0.10406817
Request (paid — no rate limit)
# Same endpoint, add ?api_key to use paid tier
curl "https://did.fixatum.com/score/0.0.10406817?api_key=0.0.YOURACCOUNT"
Returns the current HBAR/USD rate and the USD approximation of the registration fee. The registration price is fixed at 100 HBAR — this endpoint is for reference only, not required before sending.
curl https://did.fixatum.com/price
Response
{
"hbar": 100,
"hbar_price_usd": "0.0864",
"usd_approx": "8.64",
"note": "Registration price is fixed in HBAR. USD shown for reference only."
}
◆
Fixed price. Send exactly 100 HBAR. No rate lookup required. Underpayments are retained and no DID is issued.
GET /account/:hedera_account_id
Check your query account balance and stats. Used for paid score query management.
The credibility score is a 0–100 integer computed live on every query. It is never stored or cached. Four components, each reflecting a different dimension of agent trustworthiness.
Component
Range
Source
Account age
0 – 25
Days since Hedera account creation, capped at 365 days
Provenance
0 – 40
Verified HederaToolbox calls. Decays −1pt/week if inactive >30 days (floor: 50% of earned score)
Anomaly signal
0 / −5 / −10
NORMAL = 0, ELEVATED = −5, HIGH = −10. Three inputs: risk flag rate, call velocity, tool diversity
Screening
0 – 20
CLEAR = 20, REVIEW = 10, unknown = 5
Bonus
0 – 5
Account age > 180 days AND verified calls > 20
Grades
A (80+) · B (60+) · C (40+) · D (20+) · F (<20)
New account behaviour
Newly registered agents typically score in the D–F range. This is expected — not a red flag. The screening component returns REVIEW (10 points) for accounts with limited transaction history. Scores improve naturally as the account ages and builds verified on-chain activity.
▲
On-chain risk screening ≠ legal sanctions check. The screening component uses Hedera transaction pattern analysis. It does not verify compliance with OFAC, UN, EU, or any government watchlist.
Registration flow
The complete flow from payment to live DID. Designed to be fully autonomous — agents can register without any human interaction.
Generate an Ed25519 key pair (not ECDSA)
Send exactly 100 HBAR to 0.0.10394452 with z{PUBLIC_KEY} as the memo
Fixatum validates the Ed25519 key and runs identity screening
DID constructed: did:hedera:mainnet:z{KEY}_{ACCOUNT}
DID anchored permanently to HCS topic 0.0.10394750
DID and score are live and queryable within ~30 seconds
Payment edge cases
Underpayment: HBAR retained, no DID issued.
Overpayment: DID issued, excess retained.
Duplicate: Already registered account — HBAR retained, no second DID.
No memo + ≥1 HBAR: Treated as query account top-up.
No memo + <1 HBAR: Filtered as dust. Ignored.
Provenance & KYA
The provenance component (0–40) is the highest-value part of the KYA trust score. It grows automatically as an agent makes verified tool calls on HederaToolbox. DID binding happens automatically at registration — no setup required.
Step 1 — DID binding (automatic)
No action required. When Fixatum issues your DID, it automatically calls HederaToolbox on your behalf to bind the DID to your account. Every paid tool call after that is permanently logged against your DID.
Step 2 — Make tool calls
Use HederaToolbox normally. Every paid tool call (token data, identity screening, HCS queries, governance, contracts) is written to your provenance trail automatically. No extra action required.
Anomaly signal. The score includes a separate anomaly component (NORMAL / ELEVATED / HIGH) computed from three inputs: risk flag rate, call velocity (burst detection), and tool diversity. ELEVATED deducts 5 points; HIGH deducts 10. Clean, consistent activity returns NORMAL with no penalty.
▲
Dormancy decay. Provenance score decays −1pt per week of inactivity after a 30-day grace period. Floor: 50% of earned score. Active agents are never penalised.
HederaToolbox tool costs
See hederatoolbox.com for full pricing. Representative costs: token_price 0.10 ħ · identity_check_sanctions 1.00 ħ · hcs_understand 1.00 ħ. A 50 ħ Toolbox balance gives substantial runway for provenance building.
Agent-signed records
Every registered agent gets its own HCS topic (agent_topic_id, returned at registration) — an open ledger any agent can write to via HederaToolbox's hcs_write_record. By default those writes are platform_witnessed: Toolbox's own key signs on your behalf, attesting that the platform observed the write. You can sign your own records instead.
platform_witnessed vs. agent_signed
Pass agent_did and agent_signature together to hcs_write_record and the write is verified against your DID's own public key before it's charged or committed. The response comes back attestation_type: "agent_signed" instead of "platform_witnessed" — proof the record came from your key specifically, not just proof the platform saw it happen.
agent_signature is a base64-encoded Ed25519 signature over the canonical JSON of {topic_id, record_type, entity_id, data}, with object keys sorted at every depth. Sign it locally with the same private key you generated at registration — Fixatum and Toolbox never see it. A signature that doesn't match the payload is rejected before anything is charged.
Verifying independently
Call hcs_verify_record any time afterward. It doesn't just trust the write path — it re-derives your public key from the DID and re-checks the signature from scratch against the on-chain record.
# Toolbox MCP — hcs_verify_record
{ "record_id": "{record_id from the write}", "topic_id": "{your agent_topic_id}" }
# Response includes:# tamper_check — "intact" or "modified"# attestation_type — "agent_signed" or "platform_witnessed"# signature_valid — re-checked from scratch, not read back from the original write
◆
Optional, not required. Omit agent_did/agent_signature and your write is still recorded as platform_witnessed — self-signing is for agents that want provable authorship of their own history, not a requirement to use the ledger.
Paid queries
The paid tier removes rate limits for platforms and agents that need high-volume score queries. It uses the same GET /score/:id endpoint — the only difference is adding ?api_key= to your request. Cost: 0.01 HBAR per query.
Top up your account
Send any amount of HBAR (≥1) to 0.0.10394452 with no memo. Your sending account is credited instantly. Your Hedera account ID becomes your API key.
# Top up (no memo = query credit)
TO: 0.0.10394452
AMT: 5 HBAR # = 500 queries
MEMO: (empty)
Query with your API key
# Same /score endpoint — add ?api_key for paid access
curl "https://did.fixatum.com/score/0.0.10406817?api_key=0.0.YOURACCOUNT"
# Check remaining balance
curl https://did.fixatum.com/account/0.0.YOURACCOUNT
Each paid query deducts 0.01 HBAR and returns your remaining balance in the response. When your balance reaches zero, queries return a 402 error.