@circle-fin/device-checks

Collects passive device signals for Circle's partner KYB flow.

Call checkDevice before any onboarding or transaction API call to collect end-user device signals.

Installation

npm install @circle-fin/device-checks

Quick start

1. Create a device-check token (backend)

Your backend requests a short-lived token from Circle:

POST /v1/partner/clients/{clientEntityId}/device-checks
Authorization: Bearer <partner-api-key>
Content-Type: application/json

Path parameters:

| Parameter | Type | Description | |---|---|---| | clientEntityId | string (UUID) | The client entity ID returned from POST /v1/partner/clients |

Response (200 OK):

{
  "data": {
    "deviceCheckToken": "dct_abc123...",
    "expiresAt": "2026-09-01T12:05:00Z"
  }
}

The token expires within minutes. Use expiresAt to schedule a refresh — for example, set a timer to request a new token shortly before the current one expires. Send only the deviceCheckToken to the frontend — never expose the partner API key in the browser.

2. Run the device check (frontend)

import { checkDevice } from '@circle-fin/device-checks'

const { deviceId } = await checkDevice({
  token: deviceCheckToken,
  // environment: 'sandbox', // optional; defaults to 'production'
  // baseUrl: 'https://...', // optional; overrides environment
  // timeoutMs: 30000,       // optional; max wait for signal collection
})

| Option | Type | Default | Description | |---|---|---|---| | token | string | (required) | Token from POST /v1/partner/clients/{id}/device-checks | | environment | 'production' \| 'sandbox' | 'production' | Circle API environment | | baseUrl | string | (derived from environment) | Fully custom validation base URL; overrides environment | | timeoutMs | number | 30000 | Max time (ms) to wait for device signal collection |

checkDevice validates the token against Circle, collects passive device signals, and resolves with a deviceId (UUID) that uniquely identifies the device-check operation, or rejects with a typed error.

One call at a time — checkDevice rejects with DeviceCheckError if a previous call is still in flight. Disable retry/submit buttons while a check is running, or guard calls so only one is active at a time.

3. Pass deviceId to Circle APIs (backend)

Send the deviceId from the frontend to your backend, then include it in the riskSignals object on any Circle API call that accepts it.

Every call from the frontend to your backend that needs device signals must carry a fresh deviceId. Call checkDevice again (with a new token from step 1) before each such request.

// Frontend: send deviceId to your backend
const { deviceId } = await checkDevice({ token: deviceCheckToken })
await fetch('/your-backend/create-wire', {
  method: 'POST',
  body: JSON.stringify({ deviceId, /* ...other fields */ }),
})

# Backend: include deviceId in riskSignals on the Circle API call
curl -X POST https://api.circle.com/v1/banks/wires \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "clientEntityId": "a3f1b2c4-d5e6-7890-abcd-ef1234567890",
    "riskSignals": {
      "ipAddress": "203.0.113.42",
      "sessionId": "8f3b2c1a-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
      "deviceId": "2a7d9e5f-1c3b-4a8e-9f0d-6b5c4a3e2d1f"
    },
    "accountNumber": "12340010",
    "routingNumber": "121000248",
    "billingDetails": { "name": "Satoshi Nakamoto", "city": "Boston", "country": "US", "line1": "100 Money Street", "postalCode": "01234" },
    "bankAddress": { "country": "US" }
  }'

The riskSignals object is accepted on transaction and account endpoints (wire creation, mint, burn, etc.). The schema is:

| Field | Type | Description | |---|---|---| | ipAddress | string | IP address of the end user initiating the request | | sessionId | string (UUID) | Identifier for the end user's session | | deviceId | string (UUID) | Fresh deviceId from checkDevice for this frontend→backend call |

Full flow:

Partner backend    POST /v1/partner/clients/{id}/device-checks
                   → { deviceCheckToken, expiresAt }
                     send token to frontend

Partner frontend   checkDevice({ token })
                   → { deviceId }
                     send deviceId to backend

Partner backend    POST /v1/banks/wires (or mint, burn, etc.)
                   body includes riskSignals.deviceId
                   (repeat checkDevice for each new frontend→backend call)

Error handling

import {
  checkDevice,
  DeviceCheckError,
  DeviceCheckTimeoutError,
  DeviceCheckValidationError,
} from '@circle-fin/device-checks'

try {
  await checkDevice({ token })
} catch (err) {
  if (err instanceof DeviceCheckValidationError) {
    // Token invalid or expired — request a new one
  } else if (err instanceof DeviceCheckTimeoutError) {
    // Device signal collection timed out
  } else if (err instanceof DeviceCheckError) {
    // Generic device-check failure
  }
}