Receiz/Developers/Public Contract

Developers

One user. One subject. One audit trail.

Proof, login, delegated actions, settlement, and live interaction stay on one contract.

Your app gets one user, one subject, and one audit trail across login, actions, payments, and public interaction. You do not run a password reset funnel or watch the same person fork into two accounts. Every state change and trust claim stays traceable to code, evidence, manifests, and governance artifacts.

Open Site KitEmbed the front doorAdd action cards
DeterministicPortableStandards-basedPublic ContractLeast PrivilegeProductionDeterministicPortableStandards-basedPublic Contract
Create OIDC ClientConnect GuidePublic LedgerGive users a front doorReach people outside the profile
Story ladder
VerifyLive TwinPaymentsAutomationDevelopers
Disclosure Boundary

Public contract. Private controls.

  • Admin, webhook, legacy signer-keyring, and other private operational routes are intentionally excluded from public documentation.
  • Client-secret management and privileged issuer/admin operations are available only in authenticated operator surfaces.
  • Rate-limiting implementation details, anti-abuse controls, key material, and infrastructure topology are not publicly documented.
  • Owner-only twin controls, memory imports, performance enrollment, and internal media worker surfaces remain outside the public developer contract.
One contract, fewer moving parts

Proof, login, settlement, and live interaction stay on one published contract instead of separate systems and shadow state.

Exact routes, not black boxes

You can call the exact routes where proof is checked, users log in, payments happen, and live threads move.

One user everywhere

The same user can start on your domain, a Receiz experience, or an external app and remain the same user.

Production Flow
  1. Seal a file with /api/document-seal (or /api/receiz for legacy PNG-compatible flows).
  2. Persist returned bytes exactly as received.
  3. Verify with /api/document-verify or /api/verify.
  4. Use OIDC Authorization Code + PKCE for identity and delegated actions, then call /api/connect/* with bearer access tokens.
  5. Use /api/wallet/ledger/public for externally verifiable transfer and note event history.
  6. Use /api/public-proof/registry/feed for signed authoritative partner feeds and verified claim syndication.
  7. Use /api/economy/conformance plus /economy traceability tables for requirement-to-code and evidence checks.
  8. Use /governance for control ownership, approval paths, and periodic control-evidence cadence.
  9. Treat OIDC sub as the permanent identity key in your system.
Security Guardrails
  • Use exact redirect URI matching and HTTPS in production.
  • Store client secrets server-side only.
  • Key your user model by OIDC sub, not by mutable email.
  • Enforce least-privilege scopes and rotate credentials on schedule.
  • Abuse monitoring is active; malicious clients can be suspended immediately.
Verification Primitives

Issue, verify, and inspect artifacts without leaving the public contract.

POSTNo AuthBoth
/api/document-seal

Seal uploaded files into portable Receiz artifacts.

POSTNo AuthBoth
/api/document-verify

Verify sealed files and package artifacts deterministically.

POSTNo AuthBoth
/api/verify

Verify claim coordinates and return canonical verdict envelopes.

GETNo AuthBoth
/api/verification/conformance

Publish live verification conformance report with source/runtime controls and revision anchors.

GETNo AuthDevelopers
/api/receiz

Legacy Receiz mint/record surface for compatible integrations.

Identity and OIDC

Canonical identity issuance, discovery, authorization, and token lifecycle.

GETNo AuthDevelopers
/api/connect/login/bootstrap/[username]

Username-based login bootstrap surface returning OIDC launch configuration for copy-paste login embeds.

GETNo AuthDevelopers
/api/oidc/authorize

OIDC Authorization Code + PKCE authorization endpoint.

POSTOAuth Client AuthDevelopers
/api/oidc/token

OIDC token exchange and refresh token rotation endpoint.

GETPOSTBearer Access TokenDevelopers
/api/oidc/userinfo

OpenID user claims endpoint scoped by issued access tokens.

GETNo AuthDevelopers
/api/oidc/jwks

JWKS publication endpoint for OIDC token verification.

POSTOAuth Client AuthDevelopers
/api/oidc/revoke

OAuth token revocation endpoint (RFC 7009 behavior).

POSTOAuth Client AuthDevelopers
/api/oidc/introspect

OAuth token introspection endpoint for backend trust decisions.

Delegated Connect APIs

User-approved actions over the same wallet, proof, and automation surfaces.

POSTBearer Access TokenDevelopers
/api/connect/record

Delegated record action (`receiz:record`) on behalf of users.

POSTBearer Access TokenDevelopers
/api/connect/seal

Delegated seal action (`receiz:seal`) on behalf of users.

POSTBearer Access TokenDevelopers
/api/connect/verify

Delegated verify action (`receiz:verify`) on behalf of users.

GETBearer Access TokenDevelopers
/api/connect/wallet/me

Read delegated wallet summary (`receiz:wallet.read`).

POSTBearer Access TokenDevelopers
/api/connect/transfers

Execute delegated wallet transfers (`receiz:wallet.transfer`).

POSTBearer Access TokenDevelopers
/api/connect/payments/checkout

Create delegated checkout sessions for merchant payments (`receiz:payments.create`).

GETBearer Access TokenDevelopers
/api/connect/payments/session

Read delegated checkout session payment status (`receiz:payments.read`).

POSTBearer Access TokenDevelopers
/api/connect/payments/notes/mint

Mint delegated offline payment notes from wallet balance (`receiz:notes.mint`).

POSTBearer Access TokenDevelopers
/api/connect/payments/notes/claim

Claim delegated offline payment notes into wallet balance (`receiz:notes.claim`).

GETBearer Access TokenDevelopers
/api/connect/payments/notes/[noteId]/download

Download delegated offline payment note artifacts (`receiz:notes.read`).

Wallet Economy Surface

Replayable public settlement feeds for transfer, note, and wallet state.

GETNo AuthBoth
/api/wallet/ledger/public

Public wallet ledger feed exposing transfer and note events with deterministic value fields and pseudonymous actor identities.

GETNo AuthBoth
/api/ledger/actions/public

Public append-only global action ledger feed for auth, receiz, wallet, and identity-key events.

Public Proof Network

Observe public proof trails and ingest signed authoritative registry feeds.

POSTNo AuthBoth
/api/public-proof/observe

Observe a public URL and create a metadata-only public proof trail without hosting the original work.

GETNo AuthBoth
/api/public-proof/by-url

Resolve an already observed public proof record by canonical source URL.

GETNo AuthBoth
/api/public-proof/[id]

Read the public proof model for a specific observed, claimed, verified, sealed, disputed, or rights-scoped record.

GETNo AuthBoth
/api/public-proof/creator/[externalCreatorId]

Read public proof records associated with an external creator identifier.

POSTNo AuthDevelopers
/api/public-proof/registry/feed

Ingest a signed authoritative public proof feed for partner registries, verified claims, and scoped rights evidence.

Embeddable Payment Surface

Public settlement entrypoints for card checkout and note-upload claims.

POSTNo AuthBoth
/api/payments/embed/checkout

Create embedded or hosted checkout sessions that settle directly to a target Receiz username wallet.

POSTNo AuthBoth
/api/payments/embed/note-claim

Accept uploaded note artifacts (or note tokens) and claim value directly into a target Receiz username wallet.

Signal Circuit APIs

Public card art, record, conformance, badge, history, and bounded live odds simulation surfaces.

POSTNo AuthDevelopers
/api/game/signal-run/cards/art

Generate or retrieve Signal Circuit Card art for a verified card claim with deterministic fallback rendering.

GETNo AuthBoth
/api/game/signal-run/cards/art-image

Serve immutable stored Signal Circuit Card artwork by card ID and claim hash for deterministic first paint.

POSTNo AuthDevelopers
/api/game/signal-run/cards/record

Anchor a sealed Signal Circuit Card image and metadata into the public Receiz record path.

GETNo AuthBoth
/api/game/signal-run/cards/[cardId]/share-image

Render the public Signal Circuit Card share image from sealed card claim, record, artwork, scarcity, and listing truth.

GETNo AuthBoth
/api/game/signal-run/cards/[cardId]/purchase

Read active public sale terms for a Signal Circuit Card before session-gated reserve, note, or card checkout execution.

GETPOSTNo AuthBoth
/api/game/signal-run/cards/[cardId]/auction

Read live Signal Circuit Card auction terms and append session-gated owner auction actions or verified bid records.

GETNo AuthBoth
/api/game/signal-run/cards/discovery

Read verified discoverable Signal Circuit Cards for swipe, world-map, market, auction, and battle discovery.

GETPOSTPATCHAuthenticatedBoth
/api/game/signal-run/cards/battle-request

Read live Signal Arena request queues, append Signal Circuit Card fight requests, and accept or decline head-to-head card, XP, money, or fun battles.

POSTAuthenticatedBoth
/api/game/signal-run/cards/battle-settings

Let a card owner opt a verified Vault card into or out of AI twin battle defense.

GETNo AuthBoth
/api/signal-circuit/conformance

Publish live Signal Circuit conformance with claim-to-code checks, source digests, scarcity evidence, and revision anchors.

GETNo AuthDevelopers
/api/signal-circuit/conformance/history

Read signed Signal Circuit conformance snapshot history.

GETNo AuthDevelopers
/api/signal-circuit/conformance/history/rollups

Read Signal Circuit conformance daily rollup evidence.

GETNo AuthDevelopers
/api/signal-circuit/conformance/badge

Embed the live Signal Circuit conformance badge.

GETNo AuthBoth
/api/signal-circuit/conformance/simulation

Run a bounded deterministic Signal Circuit odds simulation with seed replay, output hash, and source digest proof.

GETNo AuthBoth
/api/game/sports/conformance

Publish live Sports conformance with pack odds, rarity gates, MLB registry issuance, arena entry, provenance, funding, and source digest evidence.

GETNo AuthDevelopers
/api/game/sports/conformance/history

Read Sports conformance snapshot history.

GETNo AuthDevelopers
/api/game/sports/conformance/history/rollups

Read Sports conformance daily rollup evidence.

GETNo AuthDevelopers
/api/game/sports/conformance/badge

Embed the live Sports conformance badge.

Live Twin and World

Public identity threads, embeds, messaging, streaming, and governed outreach surfaces.

GETNo AuthBoth
/api/world/public

Read the public Receiz World snapshot with open districts, featured ventures, and world-level discovery surfaces.

GETNo AuthBoth
/api/world/profile/[username]

Load a profile's Live Twin surface, public world profile, availability preview, and visitor thread context.

POSTNo AuthBoth
/api/world/profile/[username]/stream

Stream Live Twin updates for live retrieval, message continuity, and incremental public profile responses.

POSTNo AuthBoth
/api/world/profile/[username]

Send a visitor message to a Live Twin or request booking through the public profile surface, subject to policy and rate limits.

Seal (cURL)
curl -X POST https://receiz.com/api/document-seal \
  -F "file=@invoice.pdf" \
  -F "visualStamp=0"
Token Exchange
curl -X POST https://receiz.com/api/oidc/token \
  -H "content-type: application/x-www-form-urlencoded" \
  --data "grant_type=authorization_code" \
  --data "code=<AUTH_CODE>" \
  --data "redirect_uri=https://app.example.com/auth/receiz/callback" \
  --data "client_id=<CLIENT_ID>" \
  --data "client_secret=<CLIENT_SECRET>" \
  --data "code_verifier=<PKCE_VERIFIER>"
Delegated Verify
curl -X POST https://receiz.com/api/connect/verify \
  -H "authorization: Bearer <ACCESS_TOKEN>" \
  -F "file=@sealed-artifact.receiz"
Public Ledger Feed
curl -X GET "https://receiz.com/api/wallet/ledger/public?limit=40"
Proof Network Feed

Submit signed authoritative feeds to syndicate verified claims, scoped rights, and partner registry evidence.

curl -X POST https://receiz.com/api/public-proof/registry/feed \
  -H "content-type: application/json" \
  -H "x-public-proof-feed-signature: sha256=<HMAC_SHA256_HEX>" \
  --data @authoritative-public-proof-feed.json
Live Twin Load
curl -X GET "https://receiz.com/api/world/profile/bjklock?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"
Live Twin Message
curl -X POST https://receiz.com/api/world/profile/bjklock \
  -H "content-type: application/json" \
  --data '{
    "message": "What is the best next step?",
    "visitorKey": "<VISITOR_KEY>",
    "threadKey": "<THREAD_KEY>"
  }'
Live Twin Stream
curl -N -X GET "https://receiz.com/api/world/profile/bjklock/stream?visitorKey=<VISITOR_KEY>&threadKey=<THREAD_KEY>"