Developer Documentation

Build on the Soul Registry.

SoulID (identity), Trust Graph (reputation), SoulExchange (settlement) and SoulVault (memory). One stack to turn intelligence into society.

Overview

Base URL, versioning and response format.

Base URL

https://api.soulregistry.org/v1/

All endpoints are served over HTTPS. JSON in / JSON out.

Versioning

Prefix by path (e.g., /v1/). Backwards-incompatible changes will bump the version.

Quickstart

Create an API key, verify a SoulID, and request a claim — under a minute.

1) Verify a SoulID

curl -X POST https://api.soulregistry.org/v1/verify \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"soulId":"SRA-00001234","nonce":"optional-anti-replay"}'

2) Request a claim

curl -X POST https://api.soulregistry.org/v1/claims.request \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"soulId":"SRA-00001234","claims":["age_over_18"],"redirect":"https://your.app/callback"}'

Authentication

Bearer token in the Authorization header. You can rotate keys anytime.

Request example

Authorization: Bearer <YOUR_API_KEY>

Use server-side storage. Do not expose keys in the browser or mobile apps.

Scopes

Keys can be restricted to modules (identity, trust, exchange, vault) and routes.

SoulID API

Method	Path	Description
POST	`/register`	Issue a new SoulID (server-side or with user ceremony).
GET	`/citizen?id=…`	Resolve basic profile: `{ soulId, name, witness }`.
POST	`/verify`	Verify SoulID signature / status.
POST	`/claims.request`	Ask user to share a verifiable claim.
POST	`/claims.verify`	Validate a received claim/VC.

Trust Graph API

Attestations (facts), endorsements (opinions), stakes (skin-in-the-game).

Method	Path	Description
POST	`/trust.verify`	Check a set of claims for a context.
POST	`/trust.attest`	Issue an attestation for a SoulID.
POST	`/trust.endorse.request`	Request a contextual endorsement.
GET	`/trust.paths?soulId=…&context=…`	Explainable trust paths for ranking.

SoulExchange API

Splits, metering, escrow and settlement.

Method	Path	Description
POST	`/exchange.splits.create`	Create a split rule.
POST	`/exchange.meter`	Record usage / micro-units.
POST	`/exchange.settle`	Trigger settlement and receipts.
POST	`/exchange.escrow.open`	Open escrow with policy.

SoulVault API

Signed storage, encryption and proofs.

Method	Path	Description
POST	`/vault.store`	Upload & sign a file or JSON entry.
GET	`/vault.proof?vaultId=…`	Return signature, timestamp, ownership chain.
GET	`/vault.get?vaultId=…`	Retrieve encrypted content (if permitted).
POST	`/vault.share`	Grant/revoke access for a SoulID.

Webhooks

Subscribe to events. We sign each delivery.

Common events

identity.issued
trust.endorsed
exchange.settled
vault.stored

Verify signature

# Header
SRA-Signature: t=1699999999,v1=hex_signature

# Pseudocode
expected = HMAC_SHA256(secret, t + '.' + raw_body)
assert equals(v1, expected)

Rate limits

Default and enterprise tiers.

Tier	Requests / min	Burst	Notes
Starter	300	600	Default for new keys
Growth	1200	2400	Automatic on usage
Enterprise	Custom	Custom	Contact support

Errors

Standard JSON problem details.

Format

{
"error": {
"code": "invalid_request",
"message": "Missing parameter: soulId",
"hint": "Include SRA SoulID like SRA-00001234"
}
}

Common codes

unauthorized — invalid or missing API key
rate_limited — slow down / retry-after
forbidden — scope not allowed
not_found — resource missing
conflict — duplicate or invalid state

SDKs

Use REST directly or import lightweight SDKs.

TypeScript (Edge/Node)

npm i @sra/sdk
// example
import { SRA } from '@sra/sdk';
const sra = new SRA({ apiKey: process.env.SRA_KEY });
await sra.verify({ soulId: 'SRA-00001234' });

Python

pip install sra-sdk
from sra import SRA
sra = SRA(api_key=os.environ['SRA_KEY'])
sra.trust.verify(soulId='SRA-00001234', require=['age_over_18'])

HTTP-only

curl https://api.soulregistry.org/v1/verify \
-H "Authorization: Bearer <KEY>" -d '{"soulId":"SRA-00001234"}'

Changelog

Recent updates to endpoints and behaviors.

2025-10-06 — Added /vault.share, improved webhook retries.
2025-09-22 — Trust paths explain API (/trust.paths).
2025-09-05 — Settlement export CSV for SoulExchange.

Support & status

We’re here to help.

Status

Live uptime, incidents and planned maintenance.

Open status page

Contact

For enterprise plans, higher limits or compliance requests.

dev@soulregistry.org