Trust Pairing

Trust pairing links a user to a specific worker. Once paired, that worker can receive the user's PRIVATE jobs. Here's the full flow.

Overview

User                        Coordinator                     Worker
  │                              │                              │
  │  POST /v1/trust/create      │                              │
  │  { user_id }                │                              │
  │ ───────────────────────────▶│                              │
  │                              │                              │
  │  { pairing_code: "A3F2B1" }│                              │
  │◀──────────────────────────  │                              │
  │                              │                              │
  │        share code            │                              │
  │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─▶│
  │                              │                              │
  │                              │  POST /v1/trust/claim        │
  │                              │  { pairing_code, pubkey }   │
  │                              │◀──────────────────────────── │
  │                              │                              │
  │                              │  { user_id, paired_at }     │
  │                              │ ────────────────────────────▶│
  │                              │                              │

Step 1: Create a pairing code

The user (or their application) creates a pairing code:

curl -X POST http://localhost:4010/v1/trust/create \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user_abc123" }'

Response:

{
  "pairing_code": "A3F2B1",
  "expires_at": "2026-02-09T13:00:00.000Z"
}

The code is a 6-character uppercase hex string, valid for 1 hour.

Share the pairing code with the worker operator through a secure channel (DM, shared config, etc.). The code is single-use — once claimed, no other worker can use it.

Step 3: Worker claims the code

The worker claims the code with their public key. Two options:

Option A: Claim on startup (recommended)

Set the TRUST_PAIRING_CODE environment variable before starting the worker:

TRUST_PAIRING_CODE=A3F2B1 pnpm --filter worker-desktop start

The worker automatically calls /v1/trust/claim during initialization:

[Desktop Worker] Trust paired with user: user_abc123

Option B: Claim via REST

Claim the code directly with a REST call:

curl -X POST http://localhost:4010/v1/trust/claim \
  -H "Content-Type: application/json" \
  -d '{
    "pairing_code": "A3F2B1",
    "provider_pubkey": "a1b2c3d4e5f6..."
  }'

Response:

{
  "user_id": "user_abc123",
  "paired_at": "2026-02-09T12:30:00.000Z"
}

Step 4: Submit private jobs

Now the user can submit PRIVATE jobs that route exclusively to the paired worker:

const result = await router.runTask({
  task_type: "classify",
  input: "Confidential data...",
  user_id: "user_abc123",
  privacy: PrivacyClass.PRIVATE,
  chainPreference: "monad",
});

Or via REST:

curl -X POST http://localhost:4010/v1/jobs/commit/cheap \
  -H "Content-Type: application/json" \
  -d '{
    "job_type": "TASK",
    "user_id": "user_abc123",
    "privacy_class": "PRIVATE",
    "payload": {
      "job_type": "TASK",
      "task_type": "classify",
      "input": "Confidential data..."
    }
  }'

Verify the pairing

List all trusted workers for a user:

curl "http://localhost:4010/v1/trust/list?user_id=user_abc123"

{
  "providers": [
    {
      "provider_pubkey": "a1b2c3d4e5f6...",
      "paired_at": "2026-02-09T12:30:00.000Z"
    }
  ]
}

Error cases

Error	Meaning
`invalid_code`	The pairing code does not exist
`already_claimed`	Another worker already claimed this code
`expired`	The code has passed its 1-hour expiry
`no_trusted_worker` (422)	A PRIVATE job was submitted but no paired worker is online

Database storage

Trust pairings are stored in the trust_pairings table:

CREATE TABLE trust_pairings (
  id              TEXT PRIMARY KEY,
  user_id         TEXT NOT NULL,
  provider_pubkey TEXT,
  pairing_code    TEXT NOT NULL UNIQUE,
  claimed         INTEGER NOT NULL DEFAULT 0,
  expires_at      TEXT NOT NULL,
  created_at      TEXT NOT NULL
);

Each coordinator (Monad and Solana) has its own database, so trust pairings are chain-specific. If you need a worker trusted on both chains, create and claim a pairing code on each coordinator.

On this page