# USDCKit

> **⚠️ Important:** We have upgraded the product to [App Kit](https://docs.arc.io/app-kit) and recommend using it for all production deployments. USDCKit will remain available as a private beta product. Thank you.

## Introduction

USDCKit is a Node.js SDK that streamlines interactions with USDC. With USDCKit, you can integrate USDC into your applications and enable secure and efficient blockchain transactions. USDCKit aims to provide multi-chain fund orchestration features to enable USDC payment use cases like crypto acquiring (C2B), payroll (B2C), remittance (C2C), and B2B cross-border payments.

The SDK is built with TypeScript and supports high-level use cases involving stablecoins, making it an important tool for developers working with digital currencies.

This guide will help you get started quickly and efficiently, whether you're building a wallet, a payment gateway, or anything in between. It covers the following items:

- [Benefits of using USDCKit](#benefits-of-using-usdckit)
- [Quickstart to write your first line of code using USDCKit](#quickstart-steps)
- [Sample Code to run Stablecoin Acquiring Flow](./documents/Developer_Resources.Stablecoin_Acquiring_Flow.html)

### Benefits of Using USDCKit

- **Faster time-to-market**. USDCKit simplifies accepting and managing stablecoin payments with minimal code. It provides reusable payment modules and removes technical complexities for faster integration.
- **Payment Focused**. USDCKit is built to offer all the features and tools required to create a complete end-to-end stablecoin payment flow, with functionalities tailored for payment use cases. It also includes sample code for specific payment products, making it easier to develop your own. The focus of the current release is Stablecoin Acquiring use case.
- **Scalable payments without bottlenecks**. Process millions of transactions efficiently with USDCKit’s high-performance infrastructure.‍
- **Enterprise-grade compliance management**. Adhere to global regulatory standards with real-time transaction screening through Compliance Engine.‍

#### Key features

Besides basic wallet management, transfers, and balance queries, here are some of the other highlighted features that USDCKit supports that facilitate the orchestration of on-chain fund flow:

- **Fund sweeping**: Automate fund aggregation with many-to-1 transfers and optimize gas efficiency.
- **Cross-chain transfer**: Transfer funds between wallets on different chains.
- **Token Swap**: Convert one token type into another seamlessly.
- **Transaction screening**: Prevent wallets from transacting with OFAC sanctioned addresses.

## Quickstart Steps

### Setup

USDCKit is built on top of Circle Wallets’ Dev-controlled wallets. You will need to set up a [Circle Developer Console](https://console.circle.com/signup) account before using the service. Please follow these steps:

1. **Sign Up**

   Go to the [Circle Developer Console](https://console.circle.com/signup) and sign up for an account. This account will be used to manage your access to Circle’s Developer Services such as Dev-controlled wallets and smart contract platform. Follow the [instructions](https://developers.circle.com/interactive-quickstarts/get-started#create-a-web3-services-account) for more details.

2. **Generate API Key**

   Navigate to the [API & Client Keys](https://console.circle.com/api-keys) section of your project and generate a new **API Key**. Make sure to store the **API Key** securely as it will be used to authenticate your requests. Follow the [instructions](https://developers.circle.com/interactive-quickstarts/get-started#create-your-api-key) for more details.

3. **Register Entity Secret**

   Run the following command to create and register an **Entity Secret**. The command will prompt you to enter the **API Key** generated from the previous step.

   ```bash
   npx @circle-fin/usdckit register-entity-secret
   ```

   After running the command, your new **Entity Secret** will be displayed in the console and saved to an environment file (`.env` by default). A **Recovery File** is also stored (`recovery.dat` by default).

   A UI-based approach for setting up the **Entity Secret** is also [available](https://developers.circle.com/interactive-quickstarts/dev-controlled-wallets#setup-your-entity-secret).

### Installation

To install USDCKit from NPM, run the following command in your project directory:

```bash
npm install @circle-fin/usdckit
```

### Initialization

To get started with USDCKit, initialize a client with the **API Key** and [Entity Secret](https://developers.circle.com/w3s/entity-secret-management#what-is-an-entity-secret) from [Setup](#setup)

```typescript
import { createCircleClient } from '@circle-fin/usdckit'
import { ETH_SEPOLIA } from '@circle-fin/usdckit/chains'

const client = createCircleClient({
  apiKey: 'CIRCLE_API_KEY',
  entitySecret: 'CIRCLE_ENTITY_SECRET',

  // Optional.  Defaults to `ETH_SEPOLIA`
  chain: ETH_SEPOLIA,
})
```

## Usage

### Create Account

To create a new account (also known as wallet), use the [createAccount](./functions/providers_circle-wallets.createAccount.html) method. This will generate a new account that you can use for various operations such as transferring tokens and retrieving balances.

USDCKit currently supports the creation of **EOA** (Externally-Owned-Account) and **SCA** (Smart-Contract-Account). Refer to this [page](./documents/Developer_Resources.Account_Type_and_Gas_Fee_Management.html) to understand more and select the most appropriate account type for your business.

```typescript
// Creates an account on the default chain ETH_SEPOLIA (EOA)
const account = await client.createAccount()

// Creates an account on the ARB_SEPOLIA (SCA)
const account = await client.createAccount({ accountType: 'SCA', chain: ARB_SEPOLIA })
```

### Query for accounts

To query for existing accounts, use the [getAccounts](./functions/providers_circle-wallets.getAccounts.html) method. This will return the account details associated with the provided account query.

```typescript
// Query by Address
const account = await client.getAccounts({ address: '0xabc123...def456' })

// Query by refId
const account = await client.getAccounts({ refId: 'user-1' })

// Query by balance greater or equal to
const account = await client.getAccounts({ amountGte: 1000 })
```

### Fund Account with Testnet Tokens

To fund an account with testnet tokens, you can use the [drip](./functions/providers_circle-wallets.drip.html) method. This method provides native tokens, USDC, and EURC for testing purposes.

```typescript
// Receive native tokens, USDC, and EURC
await client.drip({ account })

// Receive native
await client.drip({ account, token: null })

// Receive USDC
await client.drip({ account, token: client.chain.contracts.USDC })
```

### Transfer tokens

The [transfer](./functions/actions.transfer.html) method allows the transferring of native or ERC-20 tokens between accounts. Multiple source accounts can be transferred with a single call. Fees can be controllable using the `fees` parameter. USDC can be transferred between accounts across chains via CCTP. Below are examples of how to use the `transfer()` method for each type of token.

```typescript
// Create Transfer - Native Tokens
const transaction_native = await client.transfer({
  from: account,
  to: anotherAccount,
  amount: '0.00000001', // or use base units `1n`
})

// Create Transfer - USDC
const transaction_usdc = await client.transfer({
  from: account,
  to: anotherAccount,
  token: ETH_SEPOLIA.contracts.USDC,
  amount: '0.01',
  chain: ETH_SEPOLIA,
})

// Create Transfer - EURC
const transaction_eurc = await client.transfer({
  from: account,
  to: anotherAccount,
  token: ETH_SEPOLIA.contracts.EURC,
  amount: '0.01',
  chain: ETH_SEPOLIA,
})

// Create Transfer - USDT
const transaction_usdt = await client.transfer({
  from: account,
  to: anotherAccount,
  token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
  amount: '0.01',
  chain: ETH,
})

// Create Transfer - Cross chain transfer (only supported for USDC)
const transaction_usdc = await client.transfer({
  from: accountOnETH_SEPOLIA,
  to: accountOnMATIC_AMOY,
  token: ETH_SEPOLIA.contracts.USDC,
  amount: '0.01',
})
```

#### Batch Transfer

Transfer from multiple source accounts to a single destination account

```typescript
// Create Transfer - Batch transfer
const transaction_batch = await client.transfer({
  from: [account_1, account_2],
  to: account_3,
  token: client.chain.contracts.USDC,
  amount: '0.01',
})
```

#### Sweep Tokens

[sweep](./functions/actions.sweep.html) function transfers all specified tokens from one account to another. In this example, it transfers all USDC tokens from `account_1` to `account_2`.

```typescript
const [tx] = await client.sweep({
  from: account_1,
  to: account_2,
  token: client.chain.contracts.USDC,
})
```

### Swap tokens

The [swap](./functions/actions.swapExactIn.html) action swaps one ERC-20 token for another

```typescript
// Get the quote for the swap
const quote = await client.getSwapQuote({
  tokenIn: client.chain.contracts.USDC,
  tokenInAmount: '100',
  tokenOut: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
})
// Verify the quote
if (quote.tokenInAmount < 9_500_000n) throw new Error('Quote is invalid')

// Swap 100 USDC for WETH
const txHash = await client.swap({ ...quote, account })
```

Directly swap without getting a quote

```typescript
// Swap 100 USDC for WETH
const txHash = await client.swap({
  tokenIn: client.chain.contracts.USDC,
  tokenInAmount: '100',
  tokenOut: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  account,
})
```

### Get Account Balance

Use [getTokenBalances](./functions/providers_circle-wallets.getTokenBalances.html) to retrieve the token balances for a specified account.

```typescript
const balance = await client.getTokenBalances({ account: account_2 })
```

### Enable Logging

Logging is enabled by configuring the `logLevel` parameter when creating the client. This allows you to see detailed logs of the operations performed by USDCKit, which can be helpful for debugging and monitoring purposes.

See [createCircleClient](./functions/index.createCircleClient.html) for more details.

```typescript
const client = createClient({
  ...,
  logLevel: 'debug',
})

```

## Samples

### Sample Code to run Stablecoin Acquiring Flow

Our sample code on the Stablecoin Acquiring Flow demonstrates the architecture and technical implementation of a typical acquiring platform. It guides you through the process to set up different wallets to collect stablecoin payments, and also to use different SDK methods to orchestrate the fund flow.

- Refer to the [Stablecoin Acquiring Flow sample code](./documents/Developer_Resources.Stablecoin_Acquiring_Flow.html)

## Future Plans

The current private release marks the first version of USDCKit, and we recognize that additional tools are needed to create a smooth stablecoin payment experience. As such, we are actively working on several modules and would greatly appreciate your feedback. Our roadmap includes, but is not limited to, the following:

- Gas Efficiency Enhancement
- Mass Payout of Funds
- Pull Payment/Subscription Payment

## Feedback & Support

If you have any questions or need assistance, don't hesitate to reach out to the team directly([usdckit@circle.com](mailto:usdckit@circle.com)). We're here to support you every step of the way.

Happy coding!