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.

Public proof verification is open. Production Creator and Twin APIs begin with Business.

Receiz v124 · Reality Becomes Infrastructure

The Production Runtime for Verified Civilization

The object is authority. Applications verify and retain proof at the edge; the server independently gates only the requested remote append or execution. Database state remains projection, sync and recovery beneath the proof object—it never makes the object true.

Live Kai, request-bound authenticated responses, durable plans, verified replay, private-access filtering, atomic multi-domain writes, and exact recovery coordinate production execution beneath the sealed proof object. Phi moves on one explicit rail—Settlement or Reserve—and every ambiguous result resolves before retry.

Operations Reference Open Site Kit OpenAPI Console Payment webhooks MCP Agent Server Embed the front door Add action cards

DeterministicPortableStandards-basedPublic ContractLeast PrivilegeProductionDeterministicPortableStandards-basedPublic Contract

SDK

One package for verification, public proof, canonical world planning, exact-head subject state, embedded proof authority, live Phi Settlement and Reserve execution, recovery, and webhook signatures.

npm install @receiz/sdk

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient();
const verified = await receiz.verification.verifyArtifact(file);
const authority = await receiz.identity.exchangeProofAuthority({
  artifact: identityArtifact,
  challenge,
  applicationId: "com.example.application",
  scopes: receiz.auth.scopesForRails(["settlement"])
});
const plan = await receiz.value.planSettlement(settlementInput);
const outcome = await receiz.value.executeSettlement(plan, authority);

if (outcome.status === "unknown") {
  await receiz.value.executionByIdempotencyKey(plan.idempotencyKey);
}

Agent MCP Server

Agents can use the same SDK rails through @receiz/mcp-server for verification, exact artifact custody, app-state, public store projections, tenant sessions, diagnostics, and proof queries. These artifact tools call the current SDK verifier and never create a parallel proof authority:

receiz_artifact_record_seal_plan
receiz_artifact_record_seal_execute
receiz_artifact_verify
receiz_artifact_extract_verified
receiz_artifact_round_trip_check
receiz_artifact_explain

npm install @receiz/mcp-server @receiz/sdk

{
  "mcpServers": {
    "receiz": {
      "command": "npx",
      "args": ["-y", "@receiz/mcp-server"],
      "env": {
        "RECEIZ_BASE_URL": "https://receiz.com",
        "RECEIZ_ACCESS_TOKEN": "<optional delegated Connect token>"
      }
    }
  }
}

Create OIDC Client OpenAPI Console Register endpoints MCP Agent Server Connect Guide Public Ledger Give users a front door Reach people outside the profile

Story ladder

Verify Live Twin Payments Automation Developers

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.
Internal media worker surfaces and operator-only Twin infrastructure remain outside the public developer contract; owner Twin controls require delegated Connect scopes.

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.

Authority order

Proof object first.

Proof-object-first. Receiz.com is reference behavior beneath proof and before developer rails: SDK, MCP, and AI.

Receiz law and product invariants
Sealed proof object, deterministic proof state, and verified local truth
Accepted identity proof and same-account binding
Receiz.com first-party reference behavior
SDK
MCP
AI

Profile operation law

Same admitted account. Same UID.

Receiz.com first-party username changes and full profile saves call PATCH /api/profile/me. The admitted account remains the actor, and its UID does not change during a rename.

No developer projection or auxiliary evidence can block that save or redefine the admitted identity.

The developer endpoint /api/receiz/identity/profile accepts profile intent from the admitted session or scoped OIDC actor and calls the same profile command. It requires authenticated profile intent only; SDK, MCP, and AI adapt to that same-UID behavior.

Proof-native operations reference

Developer mechanics beneath Receiz truth.

These interactive states document the current profile, proof-object continuity, bearer ownership, verification, and offline-proposal adapters. They do not replace proof objects, select the active first-party identity, or authorize Receiz.com profile behavior.

Authenticated developer adapter

Developer profile operation

/api/receiz/identity/profile accepts profile intent from the admitted session or scoped OIDC actor, calls the same Receiz.com profile command, and returns that same account UID. No developer-side authority prerequisite is inserted before the admitted profile operation.

UsernameDisplay name

Profile media remains proof-native

Publish media proofUpdate verified URL

Media is verified by its own proof operation and may then be referenced by the same neutral profile update. It never selects or replaces the admitted profile actor.

Proof-object continuity

verified enclosing artifactRecord → Seal

Admitted account → same-UID profile update → refreshed public projection

Same UID confirmed. The profile and public projection are refreshed after commit.

// The authenticated session or scoped OIDC actor remains the same UID.
await receiz.profile.update({
  username, displayName, avatarUrl
});

Reference state only. No account mutation is performed here. Emulator evidence is not production verification. Receiz law, sealed proof objects, deterministic proof state, and verified local truth remain stronger than every developer rail.

Production Flow

Create a verified proof object with @receiz/sdk assets.createProofObject; the SDK resolves the real Receiz ID, creates the native Record first, and seals the source bytes at the same native coordinates.
Persist returned bytes exactly as received.
Verify with /api/document-verify or /api/verify; native Profile Composer, Record, and Seal proof bundles remain valid, including proof objects saved before v103.
Use Receiz ID, Receiz Key, Identity Record, or Identity Seal for identity proof; publish continuity through /api/auth/receiz-id/continue only when needed.
For embedded applications, independently verify the identity artifact at the edge, obtain explicit in-application consent, and exchange it for short-lived minimum-scope authority without redirecting the person to receiz.com.
Use SDK-owned v122 world planners for canonical public command bytes and transaction digests; v122 and v123 names remain stable protocol identifiers in the current v124 distribution.
Move Phi through exactly one explicit rail: Settlement or Reserve. USD is display-only and comes from the canonical deterministic price projection.
On timeout or crash, resolve the idempotency key to committed, zero-write, or unknown before any retry.
Use OIDC Authorization Code + PKCE only for delegated actions, then call /api/connect/* with bearer access tokens.
Use /api/wallet/ledger/public for externally verifiable transfer and note event history.
Use /api/public-proof/registry/feed for signed authoritative partner feeds and verified claim syndication.
Use @receiz/mcp-server when an AI agent needs SDK-backed tools; MCP is tooling beneath Receiz proof objects and SDK/API rails, not authority.
Use /api/economy/conformance plus /economy traceability tables for requirement-to-code and evidence checks.
Use /governance for control ownership, approval paths, and periodic control-evidence cadence.
Treat verified Receiz identity proof as the account root; OIDC sub is delegated API subject beneath it.

Security Guardrails

Use exact redirect URI matching and HTTPS in production.
Store client secrets server-side only.
Key your user model by verified Receiz identity proof or delegated OIDC sub, never 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

Create an integrity-only seal; this route does not create a verified proof object.

POSTAuthenticatedDevelopers

/api/sdk/v1/assets/seal

Create the authenticated owner's native Receiz Record before sealing the source bytes at the same coordinates.

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.

Receiz ID and OIDC

Receiz ID proof publication, identity artifact recovery, discovery, authorization, and token lifecycle.

POSTNo AuthDevelopers

/api/auth/receiz-id/continue

Receiz ID proof publication endpoint for SDK-created or artifact-restored identities; signed key proof is required and Connect remains delegated API access after identity proof.

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.

POSTDELETEAuthenticatedDevelopers

/api/oidc/agent-tokens

Create and revoke scoped delegated agent tokens for MCP, CI, and trusted local developer agents. Tokens are shown once and carry audit labels.

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 integrity-only seal action (`receiz:seal`); proof objects use the authenticated SDK asset seal route.

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`).

GETPATCHBearer Access TokenDevelopers

/api/connect/twin/market/mandate

Read or update delegated Market Twin mandate settings (`receiz:twin.read`, `receiz:twin.write`).

GETPOSTBearer Access TokenDevelopers

/api/connect/twin/market/intents

Read or create delegated Market Twin intents under the user's mandate (`receiz:twin.read`, `receiz:twin.write`).

POSTBearer Access TokenDevelopers

/api/connect/twin/market/intents/[intentId]/approve

Approve a pending delegated Market Twin intent without bypassing mandate risk checks (`receiz:twin.write`).

GETBearer Access TokenDevelopers

/api/connect/twin/mind/export

Export a delegated Live Twin mind image artifact (`receiz:twin.read`).

GETPOSTBearer Access TokenDevelopers

/api/connect/twin/mind/import

Inspect or import delegated Live Twin mind artifacts after artifact signature verification (`receiz:twin.read`, `receiz:twin.write`).

GETPOSTBearer Access TokenDevelopers

/api/connect/twin/approval

Read or approve delegated public Twin promotion where the owner has automation entitlement (`receiz:twin.read`, `receiz:twin.write`).

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.

Proof Graph

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, rights-scoped, or app-state projection record.

GETNo AuthBoth

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

Read public proof records associated with an external creator identifier.

GETNo AuthBoth

/api/public-proof/namespace/[namespace]

Read public app-state projection records associated with a namespace, tenant, subdomain, or custom domain.

POSTOPTIONSBearer Access TokenDevelopers

/api/public-proof/registry/feed

Publish durable public app-state projections with delegated `receiz:record` authority; signed partner registry feeds remain supported.

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.

Universal Runtime

Embedded proof authority, exact-head subject state, and live Phi execution for any application or economy.

POSTBearer Access TokenDevelopers

/api/sdk/v1/runtime/authority-sessions/open

Open one short-lived server-custodied authority session after enclosing proof object verification, explicit consent, exact scope binding, and exact-head checks.

POSTBearer Access TokenDevelopers

/api/sdk/v1/runtime/authority-sessions/refresh

Refresh an authority session only from a fresh challenge with the same application, audience, scope, proof, owner, revocation, and exact-head bindings.

POSTBearer Access TokenDevelopers

/api/sdk/v1/runtime/authority-sessions/close

Close an authority session by appending its revocation; the handle never becomes identity or proof authority.

POSTBearer Access TokenDevelopers

/api/sdk/v1/runtime/qualify

Report available, degraded, or unavailable only from actual granted scopes, dependency health, and authenticated registry, reducer, service, and head evidence.

POSTBearer Access TokenDevelopers

/api/sdk/v1/domains/verified-additions

Return request-bound authenticated additions after an exact domain head; SDK verification is required before application callbacks receive them.

POSTBearer Access TokenDevelopers

/api/sdk/v1/domains/verified-replay

Return closed-shape authenticated replay for exact application, domain, registry, reducer, cursor, namespace, and head expectations.

POSTBearer Access TokenDevelopers

/api/sdk/v1/domains/verified-checkpoint

Return an immutable authenticated checkpoint bound to a previously verified replay head and exact namespace bytes.

POSTBearer Access TokenDevelopers

/api/sdk/v1/domains/verified-private-additions

Filter private additions before response construction and bind encrypted payloads to current viewer, grant, access-key, and domain heads.

POSTBearer Access TokenDevelopers

/api/sdk/v1/subjects/namespaces/resolve

Resolve strict byte-exact namespace projections at authenticated subject and namespace heads without replacing the enclosing proof object.

POSTBearer Access TokenDevelopers

/api/sdk/v1/execution/stage

Persist one exact canonical plan before execution and return the same authenticated handle for byte-identical staging retries.

POSTBearer Access TokenDevelopers

/api/sdk/v1/execution/execute

Execute one staged plan with atomic compare-and-swap across every exact participant head, or write zero everywhere.

GETBearer Access TokenDevelopers

/api/sdk/v1/execution/[applicationId]/[executionId]

Resolve an immutable authenticated execution outcome by application and execution identity without replanning.

GETBearer Access TokenDevelopers

/api/sdk/v1/execution/by-idempotency/[applicationId]/[domainId]/[operationKind]/[semanticIdempotencyKey]

Resolve committed, zero-write, cancelled, staged, or unknown by the exact semantic idempotency coordinates before retry.

POSTBearer Access TokenDevelopers

/api/sdk/v1/execution/cancel

Cancel an uncommitted staged plan under the same application, session, plan, and idempotency bindings with zero domain writes.

POSTBearer Access TokenDevelopers

/api/sdk/v1/identity/public-recipient/resolve

Resolve a consented public alias through privacy-safe rate limiting to an encrypted purpose-bound one-use locator without exposing private account coordinates.

POSTBearer Access TokenDevelopers

/api/sdk/v1/sources/publish

Publish exact sealed proof object bytes to content-addressed V124 custody; the publication result is coordination only and never proof, identity, ownership, access, history, or head authority.

POSTProof Object ConsentDevelopers

/api/sdk/v1/identity/proof-authority/exchange

Exchange an independently verified identity proof object and explicit in-application consent for a short-lived, non-refreshable, minimum-scope authority without redirecting the person to receiz.com.

GETBearer Access TokenDevelopers

/api/sdk/v1/auth/granted-scopes

Introspect the exact OAuth/OIDC scopes granted to the current application authority.

POSTBearer Access TokenDevelopers

/api/sdk/v1/subjects/[subjectId]/namespaces/resolve

Resolve named subject namespaces at one exact authenticated head with pinned registry and reducer digests.

POSTBearer Access TokenDevelopers

/api/sdk/v1/value/settlement/execute

Execute one canonical Phi Settlement intent atomically with exact heads, scoped authority, receipt, and zero-write failure.

POSTBearer Access TokenDevelopers

/api/sdk/v1/value/reserve/execute

Execute one canonical Phi Reserve intent atomically with exact heads, scoped authority, receipt, and zero-write failure.

GETBearer Access TokenDevelopers

/api/sdk/v1/value/executions/by-idempotency/[idempotencyKey]

Recover the exact committed, zero-write, or unknown Phi execution outcome before any ambiguous retry.

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>"