Skip to content
orangecheck
Get started

Quickstart

Nine steps to your first receipt.

From a new project to your first paid event, then signing by hand for production. Every step has the real code. Mark steps done as you go; your progress stays in this browser.

  1. 01

    Create your project

    Sign in and run the three-step wizard. Your orangecheck identity is your developer account, so there is no separate signup. You leave with a project key.

    Code
    # /me/projects/new
display_name: YourCompany
domain: yourcompany.com
mode: test
→ project_key: pk_test_a4f9k2x...
    Start a project
  2. 02

    Verify your domain

    Add a DNS TXT record or a meta tag, then verify. Test mode works without it. Live mode needs it.

    Code
    # DNS TXT at yourcompany.com
oc-verify=<token shown on /me/projects/[id]>

# OR meta tag in <head>
<meta name="oc-domain-verify" content="<token>" />
    Your projects
  3. 03

    Install the SDK

    One package, three entry points: /server for the framework adapters, /popup for sign-in, and the main entry for events, payments and sessions. The React provider comes from @orangecheck/auth-client.

    Code
    yarn add @orangecheck/me-client @orangecheck/auth-client
  4. 04

    Add the sign-in popup

    Call signInWithOc() from a click. A me.ochk.io popup signs the person in and hands back a token bound to your origin. Send it to your backend as a Bearer token, or trade it once for your own cookie.

    Code
    import { setBearerToken } from '@orangecheck/me-client';
import { signInWithOc } from '@orangecheck/me-client/popup';

button.addEventListener('click', async () => {
  const result = await signInWithOc();
  if (!result) return; // user cancelled
  setBearerToken(result.token); // me-client calls ride it
  const me = await fetch('/api/auth/me', {
    headers: { Authorization: `Bearer ${result.token}` },
  });
});
  5. 05

    Check the session on your server

    Wrap the route with withOcAuth, ocAuthExpress or ocAuthHono. No env vars, no key handling. Pass your own origin as the audience: a token issued to another site is refused.

    Code
    // pages/api/auth/me.ts
import { withOcAuth } from '@orangecheck/me-client/server';

export default withOcAuth(async (req, res) => {
  if (!req.ocSession) return res.status(401).json({ ok: false });
  res.status(200).json({
    ok: true,
    account: { id: req.ocSession.sub, did_oc: req.ocSession.did_oc },
  });
}, { audience: 'https://your-site.example' });
    Code for your stack
  6. 06

    Report an event from your backend

    Sign the request with your project secret and name who earns inside the signed body. Your backend never needs your users' session tokens. Store their did_oc once.

    Code
    // server-side · the earner rides inside the bytes you sign
import { oc } from '@orangecheck/me-client';

await oc.event.fire({
  project_key: process.env.OC_PROJECT_KEY!,
  subtype: 'session_creation', // any subtype your project enabled
  signingSecret: process.env.OC_SIGNING_SECRET!, // never in a browser
  userAddress: user.did_oc,                     // who earns
  idempotencyKey: crypto.randomUUID(),
});
    Your signing secret
  7. 07

    Smoke-test the loop

    Fire a test event from your project page and watch it land in the live stream. Test a webhook with one click. It is the same pipeline as production.

    Code
    # /me/projects/[id]
[ fire test envelope → ]
  subtype: session_creation
  ↓
  envelope id: oc-me-tx7m4f9k
  webhooks_fired: 0 (none registered yet)
  → live in /verify/[id]
    See the demo app
  8. 08

    Go live

    Set your prices and how much of each goes to your users. A verified domain and a live project mean real receipts.

    Code
    # /me/projects/[id] · config
mode: live
session_creation:    60 sats · user_share 65%
payment_authorization: 0.75% of amount · user_share 65%
    Ask for a comparison with your stack
  9. 09

    Sign by hand

    The SDK does this for you. This is the wire format if you are not using it. Signing is required in test mode as well as live. Reveal or rotate the secret on your project.

    Code
    // node · sign every /api/integrator/event POST
import { createHmac } from 'node:crypto';
const ts = Math.floor(Date.now() / 1000);
const sig = createHmac('sha256', process.env.OC_SIGNING_SECRET)
  .update(`${ts}.${rawBody}`)
  .digest('hex');
headers['X-OC-Signature'] = `t=${ts},v1=${sig}`;
    Your signing secret

Next, deeper.

The quickstart gets you to a first receipt. After that, why orangecheck compares it with other sign-ins, the sandbox runs your prices against a month of traffic, and docs.ochk.io/me/sdk documents every export.

Only want orangecheck as your sign-in, without paying your users? That is a separate, simpler integration: docs.ochk.io/integration covers making orangecheck your sign-in, or adding a did:oc to the login you already run.