# Circle's Developer Controlled Wallets NodeJS SDK

This SDK provides convenient access to Circle's Developer Controlled Wallets APIs for applications written in NodeJS. For the API reference, see the [Circle Web3 API docs](https://developers.circle.com/api-reference/wallets/common/ping).

## Installation

Install the package with:

```sh
npm install @circle-fin/developer-controlled-wallets --save
```

or

```sh
pnpm add @circle-fin/developer-controlled-wallets
```

## Usage

1. Generate an API key, if you haven't already, in the [Web3 Services Console](https://console.circle.com/api-keys). This API key will be used for authentication and authorization when making requests to Circle's APIs.

2. Generate a new entity secret by using the helper function in the SDK. This will print a new entity secret to the console which you can copy and use it in step 3 to register the secret. 

   ```javascript
   const { generateEntitySecret } = require('@circle-fin/developer-controlled-wallets')

   generateEntitySecret()
   ```

   or

   ```typescript
   import { generateEntitySecret } from '@circle-fin/developer-controlled-wallets'

   generateEntitySecret()
   ```

> [!IMPORTANT]
Protect your Entity Secret as you would protect your house key. Losing it or sharing it with others can have serious consequences. As the name suggests, the Entity Secret is sensitive information. Store it securely and treat it with the highest level of confidentiality to prevent unauthorized access or use.

3. Register the entity secret either by using the SDK or by following Circle's [Developer-Controlled QuickStart](https://developers.circle.com/wallets/dev-controlled/create-your-first-wallet). This step ensures that your account is correctly set up to interact with Circle's APIs.

   ```javascript
   const { registerEntitySecretCiphertext } = require('@circle-fin/developer-controlled-wallets')

   const response = await registerEntitySecretCiphertext({
      apiKey: '<api-key>',
      entitySecret: '<new-entity-secret>'
    })
   console.log(response.data?.recoveryFile)
   ```

   or

   ```typescript
   import { registerEntitySecretCiphertext } from '@circle-fin/developer-controlled-wallets'

   const response = await registerEntitySecretCiphertext({
      apiKey: '<api-key>',
      entitySecret: '<new-entity-secret>'
   })
   console.log(response.data?.recoveryFile)
   ```

> [!IMPORTANT] 
The `registerEntitySecretCiphertext` function downloads a recovery file named `recovery_file_<timestamp>.dat`. This file should be stored securely, similar to the entity secret. Additionally, the function returns the content of the recovery file as a JSON response. 

4. In your code, import the factory `initiateDeveloperControlledWalletsClient` from the SDK and initialize the client using your API key and entity secret:

   ```javascript
   const { initiateDeveloperControlledWalletsClient } = require('@circle-fin/developer-controlled-wallets')

   const client = initiateDeveloperControlledWalletsClient({
     apiKey: '<your-api-key>',
     entitySecret: '<your-entity-secret>',
   })
   ```

   or

   ```typescript
   import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets'

   const client = initiateDeveloperControlledWalletsClient({
     apiKey: '<your-api-key>',
     entitySecret: '<your-entity-secret>',
   })
   ```

5. Interact with the client:

   ```javascript
   const walletSetResponse = await client.createWalletSet({
     name: 'WalletSet 1',
   })

   console.log('Created WalletSet', walletSetResponse.data?.walletSet)

   const walletsResponse = await client.createWallets({
     blockchains: ['MATIC-AMOY'],
     count: 2,
     walletSetId: walletSetResponse.data?.walletSet?.id ?? '',
   })

   console.log('Created Wallets', walletsResponse.data?.wallets)
   ```

   We recommend reading through the official [documentation](https://developers.circle.com/wallets/dev-controlled) and [QuickStart guides](https://developers.circle.com/build-onchain) mentioned above to ensure a smooth setup and usage experience.

## Solana interop

The SDK ships two opt-in Solana signer adapters as subpath exports — one per Solana library generation. Importing from the package root does not pull in any Solana code; pick the subpath that matches your project.

| Solana library | Subpath |
| --- | --- |
| `@solana/kit` (web3.js v2) | `@circle-fin/developer-controlled-wallets/solana/kit` |
| `@solana/web3.js` v1 (`VersionedTransaction`) | `@circle-fin/developer-controlled-wallets/solana/web3` |

Both expose `createTransactionSigner(...)` and delegate signing to the Circle Signing API. See [`src/solana/README.md`](./src/solana/README.md) for the full reference and examples.

## Configuration

The client accepts the following configuration parameters:

| Option         | Required     | Description                                                                                                     |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `apiKey`       |      [x]       | Api Key that is used to authenticate against Circle APIs.                                                       |
| `entitySecret` |      [x]       | Your configured entity secret. You can follow the [QuickStart](https://developers.circle.com/wallets/dev-controlled/entity-secret-management) to set it up.                                                                                  |
| `baseUrl` | [ ]      | Optional base URL to override the default: `https://api.circle.com`. |
| `storage`      | [ ] | Optional custom storage solution for persisting data. We will fallback to InMemoryStorage if none was provided. |
| `userAgent` | [ ]      | Optional custom user agent request header. We will prepend it to default user agent header if provided. |

## Need help or have questions?

Here are some helpful links, if you encounter any issues or have questions about this SDK:

- 🎥 [Watch and learn](https://www.youtube.com/watch?v=17hOaMNf87s&list=PLoJwRn8qrG26yB_Y5uLpamwzp1onYMe7O): Watch our step-by-step walkthrough of our official [Developer-Controlled Wallets QuickStart](https://developers.circle.com/wallets/dev-controlled/create-your-first-wallet).
- 🎮 [Join our Discord Community](https://discord.com/invite/buildoncircle): Engage, learn, and collaborate.
- 🛎 [Visit our Help-Desk Page](https://help.circle.com/s/submit-ticket): Dive into curated FAQs and guides.
- 📧 [Direct Email](mailto:customer-support@circle.com): We're always a message away.
- 📖 [Read docs](https://developers.circle.com/wallets): Check out our developer documentation.

Happy coding!