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.

A device check records the device an end user is acting from. @circle-fin/device-checks runs the check in the browser and returns a deviceId; Circle stores the result against that identifier. Run the check once per end user and keep the deviceId. It is used in two places:

Stablecoin KYB submission. A device check is required before you submit or resubmit the application. Circle looks up the result on submit and on RFI resubmit. This also applies to PERIODIC_REVIEW and INFORMATION_UPDATE submits. The check from the client’s original onboarding counts.
Digital Asset Accounts money movement. Transfers, withdrawals, recipient addresses, and wire accounts send the deviceId as riskSignals.deviceId, and Circle resolves it against this device check. See Implement Strong Customer Authentication.

@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. Among onboarding templates, only Stablecoin KYB requires this check at submit. For other templates, go to Submit and track applications. End users of Digital Asset Accounts are onboarded through Stablecoin KYB, so this step applies to them.

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.

Store the returned deviceId and send that same value later. Do not generate your own: an identifier Circle cannot resolve makes money movement fail silently at the call site—the endpoint returns 201 and the transaction settles as failed with errorCode: transfer_denied.

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

Match

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