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 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, Sports card manifests, wallet ledger reads, Connect transfers, and webhook signatures.

npm install @receiz/sdk

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

const receiz = createReceizClient();
const verified = await receiz.verification.verifyArtifact(file);
const ledger = await receiz.wallet.publicLedger({ limit: 40 });

Agent MCP Server

Agents can use the same SDK rails through @receiz/mcp-server for verification, app-state, public store projections, tenant sessions, diagnostics, and proof queries.

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.

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

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