Integration Guide

const VEIL_API = process.env.VEIL_API_URL ?? 'https://api.13-61-145-21.sslip.io/api/v1';

// Submit a repayment event
const res = await fetch(`${VEIL_API}/scoring-events/repayments`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userPk: '0xabc123...',        // user's Veil public key (32 bytes hex)
    issuerPk: '0xdef456...',      // your registered issuer public key
    paidOnTimeFlag: 1,            // 1 = on time, 0 = late
    amountWeight: 1000,           // normalized loan size
    eventEpoch: 3,                // current protocol epoch
  }),
});
const { job } = await res.json();
// → { id: "job_...", status: "pending" }

// Request a one-time challenge (valid for 60 seconds)
const res = await fetch(`${VEIL_API}/challenges`, { method: 'POST' });
const { challenge, challengeExpiresAt } = await res.json();
// Use challenge in POST /credit-decisions within 60s

// The recommended flow uses the user's Veil DID (did:veil:0x...)
// No need to pass userPk, veilIdHash, sporeId, or userCkbAddress separately.

// 1. Get the user's Veil DID — they share it or you resolve it from their sporeId.
const veilDid = 'did:veil:0x...';                // e.g. from the user's dashboard

// 2. Obtain a fresh challenge
const { challenge } = await fetch(`${VEIL_API}/challenges`, { method: 'POST' })
  .then((r) => r.json());

// 3. Build the message the user's CKB wallet must sign
const verificationMethod = `${veilDid}#ckb-owner-1`;
const message = [
  'Veil credit decision authorization',
  `did:${veilDid}`,
  `challenge:${challenge}`,
  `verificationMethod:${verificationMethod}`,
  'registryVersion:1',
  'purpose:credit-decision',
].join('\n');

// 4. Have the user's CKB wallet sign the message (e.g. via CCC connector)
const authorization = await ckbSigner.signMessage(message);

// 5. Submit the credit decision request
const res = await fetch(`${VEIL_API}/credit-decisions`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    did: veilDid,                  // ← the Veil DID
    challenge,
    authorization: {
      ...authorization,
      verificationMethod,          // the verification method used
    },
  }),
});
const decision = await res.json();

Veil credit decision authorization
did:<did:veil:0x...>
challenge:<challengeHex>
verificationMethod:<did:veil:0x...#ckb-owner-1>
registryVersion:1
purpose:credit-decision

Veil credit decision authorization
challenge:<challengeHex>
userPk:<userPkHex>
veilIdHash:<veilIdHash>
sporeId:<sporeId>

{
  "success": true,
  "approved": true,
  "scoreBand": "gold",
  "maxLtvBps": 6500,
  "riskPremiumBps": 150,
  "hasCreditScore": true,
  "reason": "Approved for gold tier",
  "veilIdHash": "0x...",
  "validAt": "2025-06-07T12:00:00.000Z"
}

const VEIL_API = process.env.VEIL_API_URL ?? 'https://api.13-61-145-21.sslip.io/api/v1';

// Submit any scoring event
async function submitRepayment(params: {
  userPk: string;
  issuerPk: string;
  paidOnTimeFlag: 0 | 1;
  amountWeight: number;
  eventEpoch: number;
}): Promise<string> {
  const res = await fetch(`${VEIL_API}/scoring-events/repayments`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params),
  });
  if (!res.ok) throw new Error(`Submit failed: ${res.status}`);
  const { job } = await res.json();
  return job.id;
}

// Poll job until settled
async function waitForJob(jobId: string, timeoutMs = 60_000): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const { job } = await fetch(`${VEIL_API}/jobs/${jobId}`).then((r) => r.json());
    if (job.status === 'succeeded') return;
    if (job.status === 'failed') throw new Error(job.error ?? 'Job failed');
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error('Timed out waiting for job');
}

// Verify user trust using their Veil DID (recommended)
async function verifyWithDid(
  veilDid: string,
  ckbSigner: CkbSigner,  // your CCC-compatible signer
): Promise<{ approved: boolean; scoreBand: string }> {
  // 1. Obtain fresh challenge
  const { challenge } = await fetch(`${VEIL_API}/challenges`, { method: 'POST' }).then((r) => r.json());

  // 2. Build the DID authorization message
  const verificationMethod = `${veilDid}#ckb-owner-1`;
  const message = [
    'Veil credit decision authorization',
    `did:${veilDid}`,
    `challenge:${challenge}`,
    `verificationMethod:${verificationMethod}`,
    'registryVersion:1',
    'purpose:credit-decision',
  ].join('\n');

  // 3. Have the user sign with their CKB wallet
  const authorization = await ckbSigner.signMessage(message);

  // 4. Request the credit decision
  const res = await fetch(`${VEIL_API}/credit-decisions`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ did: veilDid, challenge, authorization: { ...authorization, verificationMethod } }),
  });
  if (!res.ok) throw new Error(`Decision failed: ${res.status}`);
  return res.json();
}