Cred-RepoCRED-REPO

Cred-Repo Protocol

Developer Documentation

A public record of what you said, before you knew what would happen.

Introduction

Cred-Repo records probabilistic commitments before outcomes occur and computes calibration after resolution.

Cred-Repo is a protocol for recording probabilistic commitments about real-world outcomes. Applications create actors, ensure events, and submit probability commitments. Independent resolvers attest to outcomes with verifiable evidence.

Cred-Repo measures how well probabilities match reality.

Cred-Repo does not generate predictions. Applications and actors create commitments; Cred-Repo records and evaluates them.

The protocol has two credential roles:

Application credentials

Create actors, ensure events, submit commitments, and query data.

Resolver credentials

Resolve events and attest outcomes.

When an application registers with Cred-Repo, it receives several credentials used to implement these roles.

The Ledger Model

Cred-Repo records three things.

  • →Actors make commitments
  • →Commitments reference events
  • →Resolvers attest outcomes

Scores are computed automatically.

Key rule: Commitments are written to the ledger immediately when sealed — before outcomes are known.

Events are global. Applications ensure events. Multiple applications may reference the same event key.

Actors are namespaced. Actor identities remain scoped to their application namespace.

60-Second Example

Alice predicts rain in Seattle tomorrow.

Event

weather:rain:seattle:2026-03-14
  1. 1App ensures event
  2. 2Alice commits probability 0.72
  3. 3Cred-Repo records the commitment
  4. 4Resolver posts NOAA outcome (true)
  5. 5Cred-Repo computes score

Brier Score

(0.72 − 1)² = 0.0784

Lower scores indicate better calibration.

Core Concepts

Event

A real-world question identified by a canonical key.

domain:type:entity:YYYY-MM-DD

Example: weather:rain:seattle:2026-03-14

Events are global across the network. Multiple applications can reference the same event.

Event keys must be deterministic and stable across applications.

Actor

Actors represent humans, agents, or systems that make commitments.

external_user_idYour internal user identifier (must be stable within your namespace)
handlePublic identifier (unique within your namespace, immutable once created)
display_nameOptional human-readable name
actor_typehuman, ai_agent, ensemble, or reference
identity_idOptional link to Cred-Repo identity (for cross-app profiles)

Important: external_user_id must be stable for the lifetime of the user within your app. Changing it creates a new actor and breaks prediction history.

Actors exist within an application namespace. Example: weathercred:alice

Namespace Isolation

All actors and commitments are scoped to your application namespace.

  • • Actors are namespaced — weathercred:alice and nbacred:alice are different actors
  • • Handles must be unique within your namespace only
  • • Events are global — multiple namespaces can attach commitments to the same event
  • • API queries return only actors and commitments in your namespace

Commitment

A probability prediction about an event.

actor_idCred-Repo-assigned actor UUID
event_keyCanonical event key
probability0.0–1.0
questionHuman-readable claim
resolution_dateWhen the event resolves

Each amendment creates a new sealed version. Previous versions remain permanently recorded.

Commitment Lifecycle

proposed→committed→resolved

Amendments create a new committed version while preserving previous versions in the ledger.

Lock Window

locks_at is the timestamp after which commitments cannot be created or amended.

Once locks_at has passed, the API will reject new or amended commitments with EVENT_LOCKED. Applications may check locks_at client-side to disable UI interactions before the lock occurs.

Resolver

Resolvers determine event outcomes and supply evidence. They authenticate using resolver credentials, not application credentials.

Resolvers submit:

  • • outcome — boolean or numeric depending on ruleset
  • • evidence_type — string identifier
  • • evidence_payload — object with raw data

Cred-Repo computes and stores sha256(evidence_payload) to anchor the evidence on the ledger.

Resolvers may only resolve events once. Subsequent resolution attempts will return EVENT_RESOLVED.

Scoring

Cred-Repo computes Brier scores for each commitment.

Brier = (prediction − outcome)²

Example:
  prediction = 0.72
  outcome = 1
  
  Brier = (0.72 − 1)² = 0.0784

Brier scores range from 0 (perfect calibration) to 1 (maximum error). Lower scores indicate better calibration.

API Reference

All endpoints. Click any row to expand request and response shapes.

Authentication

All requests require Authorization: Bearer YOUR_API_KEY. Keys are scoped to a single namespace.

Resolver credentials must only be used for POST /events/{key}/resolve.

Idempotency

events/ensure → idempotent
actors → idempotent by external_user_id
commitments → unique per actor + event
resolve → allowed once

Protocol Guarantees

  • • Commitments cannot be modified after sealing
  • • Events resolve once
  • • Evidence is hash-anchored
  • • Prediction history is permanent

Error Reference

Common error codes returned by the API.

Authentication Errors

invalid_api_keyAPI key is missing, malformed, or not recognized
invalid_oauth_clientOAuth client_id does not exist or is disabled
invalid_redirect_uriRedirect URI does not match any registered URI for this client

Commitment Errors

CRED_ACTOR_FAILEDFailed to create or retrieve actor in Cred-Repo
CRED_COMMITMENT_FAILEDFailed to create commitment in Cred-Repo
COMMITMENT_EXISTSA commitment already exists for this actor and event (use amend endpoint)

Event Lifecycle Errors

EVENT_CLOSEDEvent has passed its closes_at timestamp; no new commitments accepted
EVENT_LOCKEDEvent has passed its locks_at timestamp; commitments cannot be amended
EVENT_RESOLVEDEvent outcome has already been determined; no changes allowed

Code Examples

The full four-step workflow in curl, Node.js, and Python.

Curl
curl -X POST https://staging.cred-repo.com/api/v1/actors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "handle": "alice"
  }'

OAuth Integration

"Continue with Cred-Repo" — let your users log in with their Cred-Repo identity.

What it is

OAuth lets apps link users to their Cred-Repo identity for cross-application credibility. After the user approves access, your callback receives a short-lived access token, which you exchange for their identity_id and handle from /api/oauth/userinfo.

Scope: identity:read — read the user's handle and identity ID. No write access is granted.

Environment Variables

NEXT_PUBLIC_CRED_BASE_URL

Client-side — baked into your JavaScript bundle for OAuth redirects

CRED_BASE_URL

Server-side — used for token exchange and API calls

Both must point to the same Cred-Repo instance.

Examples

Local: http://localhost:3000
Staging: https://staging.cred-repo.com
Production: https://cred-repo.com

Redirect URIs

Redirect URIs must exactly match one of the URIs registered for your OAuth client, including protocol and trailing slash.

  • • Wildcard domains are not supported
  • • Query parameters must match exactly
  • • You can add additional redirect URIs from the developer dashboard

Authorization flow

  1. 1
    Redirect the user to Cred-Repo

    Send the user to /oauth/authorize with your client_id, redirect_uri, and scope=identity:read.

  2. 2
    User approves on the consent screen

    Cred-Repo shows the user which app is requesting access and what it can read. The user clicks Authorize.

  3. 3
    Cred-Repo redirects back with a code

    Cred-Repo redirects to your redirect_uri with ?code=…. The code is single-use and expires in 5 minutes.

  4. 4
    Exchange code for access token (server-side)

    POST your code + client credentials to /api/oauth/token. Never expose your client_secret in client-side code.

  5. 5
    Fetch user identity

    Call GET /api/oauth/userinfo with the access token to get the user's identity_id and handle.

Step 1 — Build the authorize URL

TypeScript
const params = new URLSearchParams({
  client_id:     process.env.NEXT_PUBLIC_CRED_OAUTH_CLIENT_ID,
  redirect_uri:  `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback/cred`,
  scope:         "identity:read",
  response_type: "code",
  state:         encodeURIComponent("/dashboard"),
});
const authorizeUrl = `${process.env.NEXT_PUBLIC_CRED_BASE_URL}/oauth/authorize?${params}`;

Step 4 — Exchange code for token

TypeScript
const tokenRes = await fetch(`${process.env.CRED_BASE_URL}/api/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type:    "authorization_code",
    code,
    redirect_uri:  `${origin}/auth/callback/cred`,
    client_id:     process.env.NEXT_PUBLIC_CRED_OAUTH_CLIENT_ID,
    client_secret: process.env.CRED_OAUTH_CLIENT_SECRET,
  }).toString(),
});
const { access_token } = await tokenRes.json();

Step 5 — Fetch user identity

TypeScript
const userRes = await fetch(`${process.env.CRED_BASE_URL}/api/oauth/userinfo`, {
  headers: { Authorization: `Bearer ${access_token}` },
});
const { identity_id, handle } = await userRes.json();

Request API Key

Get a namespace and credentials to start building.

Your credentials will include:

  • • namespace_id
  • • api_key
  • • resolver_api_key
  • • oauth_client_id
  • • oauth_client_secret
  • • webhook_secret

Credential Security

  • • API keys are securely hashed on our servers and cannot be recovered. Store them immediately after registration.
  • • Client secrets are hashed using bcrypt and cannot be recovered. If lost, generate a new OAuth client secret in the developer dashboard.
  • • Never expose your client secret or API keys in client-side code.

Required for "Continue with Cred" OAuth flow. You can add more redirect URIs later.

Architecture

Application
     ↓
Cred-Repo API
     ↓
Ledger (events + commitments + versions)
     ↑
Resolver posts outcome

Resolvers push outcomes to Cred-Repo — Cred-Repo does not fetch them.

Future Protocol Features

  • • Derived commitments from public sources
  • • Cross-application actor profiles
  • • Multi-resolver verification
  • • Deterministic replay validation
  • • On-chain anchoring of commitment hashes

Summary

Cred-Repo provides a protocol for recording probabilistic commitments about the future.

  • • Actors predict
  • • Resolvers attest outcomes
  • • Cred-Repo records history
  • • Scores measure calibration

Everything else is interpretation.