Digital Asset Accounts React Native SDK

The React Native SDK is available in sandbox only. Production support is on the roadmap.

The React Native SDK runs in your application on the end customer’s iPhone or Android-powered device. It never holds your API key: every request goes through your backend.

What you can do

Create and use a non-custodial account: sign the end customer in, register their authorization key, create a non-custodial account, and sign transfers and withdrawals from it. See Create a non-custodial account.
Read accounts and activity: read accounts, limits, deposit addresses, deposits, transactions, transfers, withdrawals, and linked bank accounts.
Approve operations with a passkey: run passkey enrollment and approval for Strong Customer Authentication (SCA).

The SDK creates accounts with a custodyType of self only. Its read methods also return other account types.

Requirements

Requirement	Minimum
React Native	0.81
React	18
Expo SDK	54, if your application uses Expo
iOS	15.0 deployment target
Android	API level 23 (`minSdk`), compile SDK 36, Android Gradle Plugin 8.9.1
Node.js (builds)	22
Passkey approvals	iOS 17.4, or Android 9 with a screen lock

Install

The SDK has two parts: the @circle-fin/daa-react-native-sdk package, and Circle’s iOS and Android SDKs, which it calls for authorization keys, signatures, and passkey ceremonies. Installing the package doesn’t download the native SDKs. Your application’s CocoaPods and Gradle builds resolve them.

Packages

Package	Purpose	Install
`@circle-fin/daa-react-native-sdk`	The SDK	`npm install @circle-fin/daa-react-native-sdk`
Expo modules	The SDK’s native modules are Expo modules. Needed only in a bare React Native application without Expo	`npx install-expo-modules@latest`
`expo-crypto`	Generates UUID v4 idempotency keys. The React Native runtime doesn’t provide a `crypto` global	`npx expo install expo-crypto`

npx expo install picks the expo-crypto version that matches your application’s Expo SDK.

iOS native SDK

The iOS native SDK is distributed from a CocoaPods spec repository. Your Podfile lists it before the CocoaPods CDN source, and pod install resolves it:

source "https://github.com/circlefin/daa-ios-sdk.git"
source "https://cdn.cocoapods.org/"

Put both source lines at the top of the Podfile, before any target block.

Android native SDK

The Android native SDK is distributed from GitHub Packages, which needs a GitHub account to read even public packages. Your application’s root build.gradle lists it in the repositories block. Read the values from environment variables so that no credentials are committed:

allprojects {
    repositories {
        // Your existing repositories
        maven {
            url System.getenv("DAA_ANDROID_MAVEN_URL")
            credentials {
                username System.getenv("DAA_ANDROID_MAVEN_USERNAME")
                password System.getenv("DAA_ANDROID_MAVEN_PASSWORD")
            }
        }
    }
}

Variable	Value
`DAA_ANDROID_MAVEN_URL`	`https://maven.pkg.github.com/circlefin/daa-android-sdk`
`DAA_ANDROID_MAVEN_USERNAME`	Your GitHub username
`DAA_ANDROID_MAVEN_PASSWORD`	A GitHub personal access token with `read:packages` scope

The Android native SDK needs compileSdkVersion 36 or later.

Builds and devices

The SDK’s native modules are linked when your application’s native projects build, for example with npx expo run:ios and npx expo run:android, or npx react-native run-ios and npx react-native run-android in a bare React Native application. Run your application on a physical iPhone or Android-powered device. The authorization key is hardware-backed, so simulators and emulators without secure key hardware can’t create one.

Initialize

The SDK has two clients. Create the one for each job that your application does.

Non-custodial accounts

DaaClient takes four required fields:

Field	Description
`appId`	A stable identifier that you choose, 1 to 41 characters from `A-Za-z0-9._-`. It names your application’s authorization keys on the device and isn’t sent to Circle
`environment`	`sandbox` or `production`
`transport`	Your `DaaTransport` implementation. It sends each request to your backend relay. The SDK never holds an API key
`keyPolicy`	Must be `DEVICE_KEY_POLICY`. The SDK rejects any other value

import { DaaClient, DEVICE_KEY_POLICY } from "@circle-fin/daa-react-native-sdk";

const daa: DaaClient = new DaaClient({
  appId: "YOUR_APP_ID",
  environment: "sandbox",
  transport: backendTransport,
  keyPolicy: DEVICE_KEY_POLICY,
});

For a DaaTransport that sends requests to your relay, see Connect your application.

Passkey approvals

createScaClient returns a client that runs Circle’s passkey ceremony in a system browser sheet: ASWebAuthenticationSession on iOS, and an Auth Tab or Custom Tab on Android.

import {
  createScaClient,
  type ScaClient,
} from "@circle-fin/daa-react-native-sdk";

const sca: ScaClient = createScaClient({
  environment: "sandbox",
  redirectUri: "https://app.example.com/sca/callback",
});

Field	Required	Description
`environment`	Yes	`sandbox` or `production`
`redirectUri`	Yes	Your registered `https` app callback URI, exactly as registered
`approveTimeoutMs`	No	How long an approval can take, in milliseconds. Defaults to 300000. Must be from 30000 to 3600000
`enrollTimeoutMs`	No	How long an enrollment can take, in milliseconds. Defaults to 600000. Must be from 30000 to 3600000

Before the first ceremony, set up the callback on each platform. See Set up the callback in the iOS SDK reference and Set up the callback in the Android SDK reference. The React Native SDK uses the same setup.

Methods

Each table lists a client’s methods, the API operation that each one calls, and whether the end customer’s authorization key signs it. Your backend relay must forward each operation that your application uses. See Set up a backend relay.

Your relay adds your API key, which can act for all of your end customers, to every request. It must authenticate the end customer and forward only the SDK’s routes. It must forward account, transfer, and withdrawal requests only for the signed-in end customer’s own non-custodial account. Circle checks the end customer’s signature only on non-custodial accounts, and your API key alone can debit a custodial account. The relay must also check that every unsigned request, such as a read, belongs to the signed-in end customer’s clientEntityId.

Sign-in is a chain: each call returns the object that you call next. DaaClient.auth is an AuthClient.

Method	Returns	Endpoint	End customer signature
`AuthClient.prepareSocialLogin({ provider })`	`PreparedSocialLogin`	`POST /v1/accounts/auth/loginRequests`	No
`PreparedSocialLogin.completeSocialSession({ idToken, clientEntityId })`	`PendingDeviceRegistration`	`POST /v1/accounts/auth/sessions`	No
`PreparedSocialLogin.abandon()`	Nothing	None. Discards the prepared login	No
`PendingDeviceRegistration.complete()`	`DeviceRegistrationResult`	`POST /v1/accounts/auth/deviceKeyRegistration`	Yes
`DaaClient.forUser(context)`	`DaaUserClient`	None. Runs on the device	No

You can use each PreparedSocialLogin and PendingDeviceRegistration once. When complete() returns a result whose status is ACTIVE, pass its context to forUser.

Signed-in end customer

DaaUserClient holds the clients in the rest of this section.

Method	Returns	Endpoint	End customer signature
`DaaUserClient.refreshContext()`	`DeviceContext`	`GET /v1/accounts/auth/context`	Yes
`DaaUserClient.close()`	Nothing	None. Every later call on this client fails	No

Accounts

Method	Returns	Endpoint	End customer signature
`accounts.create(request)`	`Account`	`POST /v1/accounts`	Yes
`accounts.list(query?)`	`Page<Account>`	`GET /v1/accounts`	No
`accounts.get(accountId)`	`Account`	`GET /v1/accounts/{id}`	No
`accountLimits.get(accountId, query?)`	`AccountLimitsUsage`	`GET /v1/accounts/{id}/limits/usage`	No
`depositAddresses.create(request)`	`AddressObject`	`POST /v1/accounts/addresses/deposit`	No
`depositAddresses.list(query?)`	`Page<AddressObject>`	`GET /v1/accounts/addresses/deposit`	No
`depositAddresses.get(depositAddressId)`	`AddressObject`	`GET /v1/accounts/addresses/deposit/{id}`	No

Money movement

Method	Returns	Endpoint	End customer signature
`transfers.create(request)`	`Transfer`	`POST /v1/accounts/transfers`	Yes
`transfers.list(query?)`	`Page<Transfer>`	`GET /v1/accounts/transfers`	No
`transfers.get(transferId)`	`Transfer`	`GET /v1/accounts/transfers/{id}`	No
`withdrawals.create(request)`	`WithdrawalDetail`	`POST /v1/accounts/withdrawals`	Yes
`withdrawals.list(query?)`	`Page<WithdrawalDetail>`	`GET /v1/accounts/withdrawals`	No
`withdrawals.get(withdrawalId)`	`WithdrawalDetail`	`GET /v1/accounts/withdrawals/{id}`	No
`deposits.list(query?)`	`Page<DepositSummary>`	`GET /v1/accounts/deposits`	No
`deposits.get(depositId)`	`Deposit`	`GET /v1/accounts/deposits/{id}`	No
`transactions.list(query?)`	`Page<Transaction>`	`GET /v1/accounts/transactions`	No

Bank accounts

Method	Returns	Endpoint	End customer signature
`fiatAccounts.wires.list(query?)`	`WireSummary[]`	`GET /v1/banks/wires`	No
`fiatAccounts.wires.get(fiatAccountId)`	`Wire`	`GET /v1/banks/wires/{id}`	No
`fiatAccounts.wires.getInstructions(fiatAccountId, query?)`	`WireInstruction`	`GET /v1/banks/wires/{id}/instructions`	No
`fiatAccounts.ach.list({ clientEntityId })`	`ACH[]`	`GET /v1/banks/ach`	No
`fiatAccounts.ach.get(fiatAccountId)`	`ACH`	`GET /v1/banks/ach/{id}`	No
`fiatAccounts.ach.getInstructions(fiatAccountId)`	`ACHInstruction`	`GET /v1/banks/ach/{id}/instructions`	No

Passkey approvals

Method	Returns	Description
`ScaClient.enroll(frameToken)`	`string`	Runs passkey enrollment. Send the returned registration response to your backend unchanged
`ScaClient.approve(frameToken)`	`string`	Runs an approval. Your backend sends the returned value, unchanged, in the `X-Sca-Assertion` header
`ScaClient.capabilities()`	`ScaCapabilities`	Reports whether this device can run a ceremony, such as whether the callback is set up and platform passkeys are available

Your backend gets each frameToken from Circle. One ceremony runs at a time.

Pages

List methods return a Page. items holds the results. next() and previous() return the adjacent page, or null when there isn’t one.

import type { Page, Transfer } from "@circle-fin/daa-react-native-sdk";

let page: Page<Transfer> | null = await user.transfers.list();
while (page !== null) {
  for (const transfer of page.items) {
    console.log(transfer.id);
  }
  page = await page.next();
}

Limitations

Recipient addresses, account update, and account archive: not in the SDK. Call these from your backend.

For limitations of non-custodial accounts themselves, see Limitations in the sandbox preview.

Errors

The non-custodial clients throw DaaError. The passkey client throws ScaError.

`DaaError`

Check an error with isDaaError, then read err.detail.kind:

import { isDaaError } from "@circle-fin/daa-react-native-sdk";

try {
  await user.transfers.create(transferRequest);
} catch (err: unknown) {
  if (isDaaError(err) && err.detail.kind === "transport") {
    // You don't know whether Circle received the transfer. Retry with the same
    // body and idempotency key, or read the original transfer.
  }
}

`kind`	Cause	What to do
`api`	Circle returned an error status. Read `httpStatus` and `daaStatusCode`	Retry only when `retryable` is `true`, with the same body and key
`idempotency_conflict`	Circle already has a transfer or withdrawal with this key. Account creation never throws it	Find the original with a `list` call. Use a new key only if it’s `failed`
`transport`	Your `DaaTransport` threw before a response arrived, so you don’t know whether Circle received the request. `err.cause` holds your error	Retry with the same body and the `idempotencyKey` on the error, or read the original resource
`login_request_expired`	The prepared login expired	Start again with a new `prepareSocialLogin` call
`local_user_authentication_required`	The end customer didn’t confirm with biometrics or, on an iPhone, the screen lock	Ask the end customer to try again
`device_not_initialized`	The authorization key isn’t available on this device	Sign the end customer in again
`contract_violation`	A request or response didn’t match the expected format, a key operation on the device failed, or the registered authorization key is no longer active	An integration bug, such as a changed body in your relay. Don’t retry automatically

During completeSocialSession, an api error with httpStatus 403 means Circle didn’t accept the sign-in. For example:

A different Google Account is already linked to the clientEntityId that you sent.
The ID token is invalid or expired.
The ID token’s nonce doesn’t match the prepared login.
The end customer is blocked.
In production, the ID token’s aud isn’t an approved client ID. See Register your Google client IDs.

Start again with a new prepareSocialLogin call. Don’t retry with a different clientEntityId. During sign-in (prepareSocialLogin, completeSocialSession, and complete), errors that your DaaTransport throws pass through unchanged and aren’t DaaError. Start again with a new prepareSocialLogin call. Never log ID tokens, signatures, or key material.

`ScaError`

Check an error with isScaError, then read err.code. err.reason narrows some codes, such as NoAllowedBrowser or CallbackNotRouted for Unsupported, and is null otherwise.

import { isScaError } from "@circle-fin/daa-react-native-sdk";

try {
  const assertion: string = await sca.approve(frameToken);
} catch (err: unknown) {
  if (isScaError(err) && err.code === "Cancelled") {
    // The end customer closed the sheet. Let them try again.
  }
}

`code`	Cause	What to do
`Cancelled`	The end customer closed the ceremony	Let them try again
`Expired`	The frame token or the ceremony timed out	Ask your backend for a new frame token
`AlreadyEnrolled`	The end customer already has a passkey on this device	Skip enrollment
`Unsupported`	The device can’t run the ceremony. Read `reason`	Check `capabilities()`, your callback setup, and the device’s browser
`CeremonyInProgress`	Another ceremony is already open	Wait for it to finish
`Transport`	On Android, the browser couldn’t verify your App Link in time, usually because the device is offline	Retry once with a new frame token. If it keeps failing, ask the end customer to check their connection
`Protocol`	The ceremony returned an unexpected result, such as an invalid frame token	An integration bug. Don’t offer a different authentication method instead
`InvalidConfiguration`	A `createScaClient` field is invalid	Fix the configuration
`NativeModuleUnavailable`	The native module isn’t linked	Rebuild your application’s native projects

Versions

The SDK follows semantic versioning. Before version 1.0.0, a minor version can include breaking changes, so pin an exact version. Each version of the package pins the iOS and Android SDK versions that it was tested with.

Developer-controlled wallets

User-controlled wallets

Modular wallets