How-to: Collect device risk signals

The End User Onboarding API base URL is https://api-sandbox.circle.com for sandbox and https://api.circle.com for production. All requests require a Bearer token obtained via Circle key exchange in the Authorization header. All POST requests require an X-Idempotency-Key header with a client-generated UUID v4.

Stablecoin KYB requires a Persona Sentinel device check before you submit or resubmit the application. Install @circle-fin/device-checks and call checkDevice in the browser. The SDK loads an iframe, Circle records the result, and you then call submit. Circle looks up that result on submit and RFI resubmit.

@circle-fin/device-checks is web only. It cannot run in Node.js or other server-side environments.

Prerequisites

Before you begin, ensure that you’ve:

Obtained an API key for the End User Onboarding API from the Circle Console.
Created and populated a Stablecoin KYB application. See Create and populate applications.

Steps

Step 1. Check whether your template requires a device check

Confirm that the application uses a Stablecoin KYB template. Only Stablecoin KYB requires this check. For other templates, go to Submit and track applications.

Step 2. Run `checkDevice` in the browser

Install the SDK in your web project:

npm install @circle-fin/device-checks

Follow the @circle-fin/device-checks README for token setup and options. Then call checkDevice in your web client:

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

const { deviceId }: { deviceId: string } = await checkDevice({
  token: deviceCheckToken, // mint a short-lived token per the README
  environment: "sandbox", // use "production" for live applications
});

checkDevice loads an iframe and collects device signals. Circle records the result. For the full list of options, see the @circle-fin/device-checks README.

Step 3. Submit the application

Call POST .../submit (or resubmit after you address RFIs). See Submit and track applications. Use code to identify the outcome. A declined device check still submits. Review of a declined check is manual.

Result	HTTP	Code	Status	Partner action
Device check recorded as approved or declined	`200`	—	`SUBMITTED`	Continue.
Device check was not run	`404`	`181110`	Unchanged	Run `checkDevice`, then retry submit.
Device check has not finished	`504`	`181111`	Unchanged	Retry submit later.
Device-check lookup failed	`500`	`181108`	Unchanged	Retry later.

181110 and 181103 both return HTTP 404 and message: "Not found". 181111 and 181109 both return HTTP 504 and message: "Gateway timeout". Use code to tell them apart.

Mint

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Collect device risk signals

Prerequisites

Steps

Step 1. Check whether your template requires a device check

Step 2. Run `checkDevice` in the browser

Step 3. Submit the application

​Prerequisites

​Steps

​Step 1. Check whether your template requires a device check

​Step 2. Run checkDevice in the browser

​Step 3. Submit the application

Prerequisites

Steps

Step 1. Check whether your template requires a device check

Step 2. Run `checkDevice` in the browser

Step 3. Submit the application