SINAI STANDARD

Compliance Oracle

REST API server bridging off-chain KYC verification with on-chain allowlist management

Compliance Oracle

The Compliance Oracle is an Express server that connects off-chain KYC providers (Sumsub, Jumio, Onfido) to on-chain allowlist programs. When a user passes KYC, the Oracle automatically adds their wallet to the token's allowlist. When verification is revoked, the wallet is removed.

KYC Provider → POST /v1/kyc/webhook → Oracle → Allowlist Program (on-chain)

Quick Start

1. Install

cd packages/oracle
pnpm install

2. Configure Environment

# .env
SOLANA_RPC_URL=https://api.devnet.solana.com
WALLET_PATH=~/.config/solana/id.json
KYC_PROVIDER=mock          # mock | sumsub | jumio | onfido
KYC_API_KEY=your-api-key
KYC_API_SECRET=your-secret
PORT=3000

3. Start the Server

pnpm dev

The server starts on http://localhost:3000. Check health at GET /health.

Environment Variables

VariableDefaultDescription
PORT3000Server port
SOLANA_RPC_URLhttp://127.0.0.1:8899Solana RPC endpoint
REDIS_URLredis://127.0.0.1:6379Redis connection for job queue
WALLET_PATH~/.config/solana/id.jsonKeypair file path (must have authority over allowlist)
MAX_BATCH_SIZE20Wallets per allowlist transaction
KYC_PROVIDERmockKYC adapter: mock, sumsub, jumio, onfido
KYC_API_KEY—KYC provider API key
KYC_API_SECRET—KYC provider secret (not needed for Onfido)
DEFAULT_MINT—Fallback mint address for KYC webhooks

REST API

All endpoints are prefixed with /v1.

Allowlist

MethodPathDescription
POST/v1/allowlist/:mint/walletsAdd wallets to allowlist (batched)
DELETE/v1/allowlist/:mint/walletsRemove wallets from allowlist
GET/v1/allowlist/:mint/walletsList all allowlisted wallets
GET/v1/allowlist/:mint/check/:walletCheck if a wallet is allowlisted
POST/v1/allowlist/:mint/syncForce sync with KYC provider

Add Wallets

// POST /v1/allowlist/<mint>/wallets
const res = await fetch(`${ORACLE_URL}/v1/allowlist/${mint}/wallets`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    wallets: ["wallet1...", "wallet2...", "wallet3..."],
  }),
});
 
// Response
// {
//   "success": true,
//   "mint": "...",
//   "walletsQueued": 3,
//   "batches": 1,
//   "results": [{ "id": "...", "status": "pending" }]
// }

Wallets are batched into groups of MAX_BATCH_SIZE (default 20) and submitted as on-chain transactions.

Check Wallet

// GET /v1/allowlist/<mint>/check/<wallet>
const res = await fetch(
  `${ORACLE_URL}/v1/allowlist/${mint}/check/${wallet}`
);
 
// { "mint": "...", "wallet": "...", "verified": true }

Token Configuration

MethodPathDescription
GET/v1/tokens/:mint/configGet compliance configuration
PATCH/v1/tokens/:mint/configUpdate compliance parameters
// GET /v1/tokens/<mint>/config
// Returns: { mint, allowlist, tax, holdPeriod, router }
 
// PATCH /v1/tokens/<mint>/config
const res = await fetch(`${ORACLE_URL}/v1/tokens/${mint}/config`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ tax: { bps: 200 } }),
});

KYC

MethodPathDescription
POST/v1/kyc/webhookReceive KYC provider callback
GET/v1/kyc/status/:walletCheck wallet KYC status
GET/v1/kyc/verifiedList all verified wallets

The KYC webhook endpoint is called by your KYC provider (Sumsub, Jumio, Onfido) when a user's verification status changes. The Oracle parses the provider-specific payload and automatically updates the on-chain allowlist.

// GET /v1/kyc/status/<wallet>
const res = await fetch(`${ORACLE_URL}/v1/kyc/status/${wallet}`);
 
// { "verified": true, "walletAddress": "...", "provider": "sumsub" }

See KYC Providers for provider-specific configuration.

Webhooks

MethodPathDescription
POST/v1/webhooksRegister a webhook
GET/v1/webhooksList registered webhooks
DELETE/v1/webhooks/:idRemove a webhook

See Webhooks for event types and delivery details.

WebSocket

Real-time event streaming is available at ws://host:port/ws. See Real-Time Monitoring.

Architecture

                  +-----------------+
                  |   Dashboard     |
                  |  (Next.js 14)   |
                  +--------+--------+
                           |
                  +--------v--------+
                  | Compliance      |
                  | Oracle (Express)|
                  +---+----+----+---+
                      |    |    |
           +----------+    |    +----------+
           |               |               |
  +--------v---+  +--------v---+  +--------v--------+
  | KYC        |  | Chain      |  | Webhook         |
  | Adapters   |  | Listener   |  | Dispatcher      |
  +------------+  +------+-----+  +-----------------+
                         |
              +----------v----------+
              |   Solana (Token-2022) |
              |   Allowlist Program   |
              +-----------------------+

The Chain Listener subscribes to on-chain program logs and emits events to both the Webhook Dispatcher (for HTTP delivery) and WebSocket clients (for real-time streaming).

On this page