Oracle System

The Oracle is Checkpoint’s verification layer. It queries offchain points APIs, generates cryptographic signatures for accepted observations, and the blockchain verifies that an authorized oracle signer issued each claim. Source accuracy and oracle operation remain trust assumptions. For deposits, the flow is now split into two steps:

The account owner signs a short-lived authorization for a specific pointsId and operator.
The oracle verifies that authorization, fetches the latest points balance, and signs the deposit claim that the Deposit contract checks onchain, subject to available capacity and review.

Authorization and claims are short-lived. Use the returned expiry timestamps, request fresh authorization when needed, and submit signed claims promptly. This keeps the points holder account and the EVM wallet submitting the transaction explicitly separate.

The Problem It Solves

How do we know users really have the points they claim without requiring projects to set up special infrastructure?

Option 1: Require database access: Projects expose their database, which is risky and adds work
Option 2: Require special APIs: Projects build custom endpoints just for Checkpoint
Option 3: Query existing APIs: The oracle uses the project’s existing API and signs the verified result

The contracts verify the oracle signature before a deposit or settlement can proceed. The oracle checks balances, deposit limits, and market availability before issuing a claim.

How It Works

Account Model

account is the canonical ERC-7930 representation of the underlying points holder, such as an EOA
operator is the EVM wallet allowed to perform the onchain deposit for that account
The oracle normalizes the input account before signing or verifying claims

For a portable EVM account without an embedded chain reference, the canonical ERC-7930 encoding is:

0x000100000014<20-byte-address>

For example, the account for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 is:

0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045

Easy Project Integration

Anyone can integrate their project into Checkpoint To get your project’s points integrated into Checkpoint’s Oracle system and the Points Aggregator simply create an adapter in the points-adapters repository.

How It Works

An adapter is a simple piece of code that:

Takes a user’s account identifier as input
Queries your project’s existing points API
Returns the points data in a standardized format

What You Need to Do

Create an adapter using standard web APIs
Define key exports: fetch, data, total, and optional rank and deprecated
Submit a pull request to the points-adapters repository

No need to build custom infrastructure, expose your database, or create special endpoints. Read more about getting started.

Types of Verifications

1. Deposit Authorization

POST /claim/deposit/authorization

Resolve the requested account
Return the nonce, expiry, and EIP-712 payload that the account owner must sign
Full documentation →

Example Request

curl -X POST "https://oracle.checkpoint.exchange/claim/deposit/authorization" \
  -H "Content-Type: application/json" \
  -d '{
    "pointsId": "1",
    "account": "0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045",
    "operator": "0x69155e7ca2e688ccdc247f6c4ddf374b3ae77bd6"
  }'

The response includes a JSON-safe typedData view plus the raw authorization fields. With viem, rebuild the typed data using bigint values before signing.

2. Deposit Claim

POST /claim/deposit

Verify the signed deposit authorization
Fetch the latest points balance
Apply first-deposit capacity limits and review any delayed amount
Return ready with a signature, or review_required with a zero claim and null signature
Submit the claim to Deposit.deposit(...) when its status is ready
Full documentation →

Example Request

curl -X POST "https://oracle.checkpoint.exchange/claim/deposit" \
  -H "Content-Type: application/json" \
  -d '{
    "pointsId": "1",
    "account": "0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045",
    "operator": "0x69155e7ca2e688ccdc247f6c4ddf374b3ae77bd6",
    "authorization": {
      "nonce": "0",
      "expiry": "1760896448",
      "signature": "0xabc123..."
    }
  }'

Example Response

{
  "success": true,
  "claim": {
    "chainId": "421614",
    "pointsId": "1",
    "account": "0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045",
    "operator": "0x69155e7ca2e688ccdc247f6c4ddf374b3ae77bd6",
    "amount": "1000000000000000000000",
    "expiry": "1760896448",
    "nonce": "0"
  },
  "signature": "0xd1ede18..",
  "observedAmount": "5314000000000000000000",
  "delayedAmount": "4314000000000000000000",
  "availableCapacity": "49000000000000000000000",
  "status": "ready"
}

This illustrative partial deposit signs 1,000 points of a 5,314-point observation. Capacity is a snapshot, not a guarantee for the next request.

3. Settlement

POST /claim/settlement

Verify that a trade was properly settled onchain
Return the oracle signature for the settlement transaction
Full documentation →

Example Request

curl -X POST "https://oracle.checkpoint.exchange/claim/settlement" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 42161,
    "evm_tx": "0xabc..",
    "offerId": "123"
  }'

Example Response

{
  "success": true,
  "claim": {
    "chainId": "421614",
    "offerId": "123",
    "account": "0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045",
    "settlementChainId": "42161",
    "txhash": "0xabc..",
    "expiry": "1760896448",
    "nonce": "0"
  },
  "signature": "0xd1ede18.."
}

Deposit Capacity and Review

First deposits may be fully available, partially available, or require review. Read GET /ratelimits for current limits and capacity, and GET /markets for market availability. Use GET /deposits?account=... to follow review progress without signing again. When ready, request fresh authorization and a claim, then submit it promptly. If you already deposited the available portion, the oracle reviews and updates the remainder automatically. Review times can vary. Use the returned status and timestamps rather than a fixed waiting period.

Tracking Historical Changes

The oracle periodically checks deposited accounts and submits approved balance changes through changePoints(). Updates are subject to review and may not appear immediately. GET /signatures reports review status; clients do not need to submit points-change signatures themselves. Learn how to query receipt history here.

Market Availability

Points-source interruptions or unusual balance changes can delay reviews or pause oracle updates. Check GET /markets for availability and GET /deposits for your deposit’s status. An oracle pause affects claim issuance and balance updates; it does not necessarily pause other onchain activity.

API Reference

The Oracle provides endpoints for interacting with claim verification.

Try it now! Visit the Oracle API playground to test the endpoints interactively. Fill in your parameters and click “Try it Now” to see live responses from the Oracle.

Get Started

Checkpoint Products

Architecture

Oracle API Reference

Points API Reference

Brand

Legal

Oracle System

Oracle System

The Problem It Solves

How It Works

Account Model

Easy Project Integration

How It Works

What You Need to Do

Types of Verifications

1. Deposit Authorization

2. Deposit Claim

3. Settlement

Deposit Capacity and Review

Tracking Historical Changes

Market Availability

API Reference

​Oracle System

​The Problem It Solves

​How It Works

​Account Model

​Easy Project Integration

​How It Works

​What You Need to Do

​Types of Verifications

​1. Deposit Authorization

​2. Deposit Claim

​3. Settlement

​Deposit Capacity and Review

​Tracking Historical Changes

​Market Availability

​API Reference

Oracle System

The Problem It Solves

How It Works

Account Model

Easy Project Integration

How It Works

What You Need to Do

Types of Verifications

1. Deposit Authorization

2. Deposit Claim

3. Settlement

Deposit Capacity and Review

Tracking Historical Changes

Market Availability

API Reference