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 compatible with popular open-source clients like viem, web3.js, and ethers.js, and can also function as a standalone client. The SDK is built with TypeScript and supports high-level use cases involving USDC, 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:
Besides basic wallet management, transfers, and balance queries, USDCKit supports the following features:
USDCKit is built on top of Circle Wallets’ Dev-controlled wallets. You will need to set up a Circle Developer Console account before using the service. Please follow these steps:
Sign Up
Go to the Circle Developer Console 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 for more details.
Generate API Key
Navigate to the API & Client 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 for more details.
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.
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.
To install USDCKit from NPM, run the following command in your project directory:
npm install @circle-fin/usdckit
To get started with USDCKit, initialize a client with the API Key and Entity Secret from Setup
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,
})
To create a new account (also known as wallet), use the createAccount method. This will generate a new account that you can use for various operations such as transferring tokens and retrieving balances.
// Creates an account on the default chain ETH_SEPOLIA
const account = await client.createAccount()
To query for existing accounts, use the getAccounts method. This will return the account details associated with the provided account query.
// 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 })
To fund an account with testnet tokens, you can use the drip method. This method provides native tokens, USDC, and EURC for testing purposes.
// 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 })
The transfer 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.
// 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: client.chain.contracts.USDC,
amount: '0.01',
})
// Create Transfer - Cross chain USDC
const transaction_usdc = await client.transfer({
from: accountOnETH_SEPOLIA,
to: accountOnMATIC_AMOY,
token: ETH_SEPOLIA.contracts.USDC,
amount: '0.01',
})
Transfer from multiple source accounts to a single destination account
// 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 function transfers all specified tokens from one account to another. In this example, it transfers all USDC tokens from account_1 to account_2.
const [ tx ] = await client.sweep({
from: account_1,
to: account_2,
token: client.chain.contracts.USDC,
})
Use getTokenBalances to retrieve the token balances for a specified account.
const balance = await client.getTokenBalances({ account: account_2 })
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 for more details.
const client = createClient({
...,
logLevel: 'debug',
})
For more details on how to run an end-to-end USDC Acquiring Flow to support your business, refer to the USDC Acquiring Flow sample code
The current private release marks the first version of USDCKit, and we recognize that additional tools are needed to create a smooth USDC 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:
If you have any questions or need assistance, don't hesitate to reach out to the team directly(usdckit@circle.com). We're here to support you every step of the way.
Happy coding!