@circle-fin/usdckit - v0.18.0
    Preparing search index...

    Class CircleDeveloperControlledWalletsClient

    A class-based client for Circle's Developer Controlled Wallets. All operations are available as class methods.

    import { CircleDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets'

    const client = new CircleDeveloperControlledWalletsClient({
      apiKey: 'YOUR_KEY',
      entitySecret: 'YOUR_SECRET',
    })

    const response = await client.listWallets()
    console.log(response.data?.wallets)
    Index

    Developer Account

    generateEntitySecretCiphertext getPublicKey

    Faucet

    requestTestnetTokens

    Monitored Tokens

    createMonitoredTokens deleteMonitoredTokens listMonitoredTokens updateMonitoredTokens updateMonitoredTokensScope

    Other

    constructor

    Signing

    signDelegateAction signMessage signTransaction signTypedData

    Token Lookup

    getToken

    Transactions

    accelerateTransaction cancelTransaction createContractExecutionTransaction createTransaction estimateContractExecutionFee estimateTransferFee getTransaction listTransactions validateAddress

    Wallet Sets

    createWalletSet getWalletSet listWalletSets updateWalletSet

    Wallets

    createWallets deriveWallet getWallet getWalletNFTBalance getWalletsWithBalances getWalletTokenBalance listWallets updateWallet

    Webhook Subscriptions

    createSubscription deleteSubscription getNotificationSignature getSubscription listSubscriptions updateSubscription

    Developer Account

    • Generate a new entity secret.

      Returns Promise<string>

      const entitySecretCiphertext = await client.generateEntitySecretCiphertext()
      console.log(entitySecretCiphertext)

    • Get the public key associated with your entity.

      Returns Promise<TrimDataResponse<PublicKey>>

      const response = await client.getPublicKey()
      console.log(response.data.publicKey)

    Faucet

    • Request testnet tokens for your wallet.

      Parameters

      Returns Promise<AxiosResponse<void, any>>

      const response = await client.requestTestnetTokens({
        address: '0xb395f4ea0ba29494ce839613fffba74279579269',
        blockchain: TestnetBlockchain.EthSepolia,
        usdc: true,
      })
      console.log(response.status)

    Monitored Tokens

    • Add a new token to the monitored token list.

      Parameters

      • input: CreateMonitoredTokensInput

      Returns Promise<TrimDataResponse<MonitoredTokens>>

      const response = await client.createMonitoredTokens({
        tokenIds: ['4fdb0a55-cb17-4db5-b5a7-2cca2b26dfd6'],
      })
      console.log(response)

    • Delete tokens from the monitored token list.

      Parameters

      • input: DeleteMonitoredTokensInput

      Returns Promise<AxiosResponse<void, any>>

      const response = await client.deleteMonitoredTokens({
        tokenIds: ['4fdb0a55-cb17-4db5-b5a7-2cca2b26dfd6'],
      })
      console.log(response)

    • Get monitored tokens.

      Parameters

      • Optionalinput: ListMonitoredTokensInput

      Returns Promise<TrimDataResponse<MonitoredTokens>>

      const response = await client.listMonitoredTokens()
      console.log(response)

    • Edit the monitored token list.

      Parameters

      • input: UpdateMonitoredTokensInput

      Returns Promise<TrimDataResponse<MonitoredTokens>>

      const response = await client.updateMonitoredTokens({
        tokenIds: ['4fdb0a55-cb17-4db5-b5a7-2cca2b26dfd6'],
      })
      console.log(response)

    • Select between monitoring all tokens or selected tokens added to the monitored tokens list.

      Parameters

      • input: UpdateMonitoredTokensScopeInput

      Returns Promise<AxiosResponse<void, any>>

      const response = await client.updateMonitoredTokensScope({
        scope: 'MONITOR_ALL',
      })
      console.log(response)

    Other

    • Creates an instance of CircleDeveloperControlledWalletsClient.

      Parameters

      • config: ClientParams

        API key, entity secret, optional baseUrl.

      Returns CircleDeveloperControlledWalletsClient

    Signing

    • Sign a delegate action from a specific developer-controlled wallet.

      NOTE: This endpoint is only available for NEAR and NEAR-TESTNET.

      Parameters

      • input: SignDelegateActionInput

      Returns Promise<TrimDataResponse<SignDelegateActionResponse>>

      const response = await client.signDelegateAction({
        walletId: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        unsignedDelegateAction: 'ASVlcGFrcm...VkZHlndW1taS==',
      })
      console.log(response.data?.signature)

    • Sign the EIP-191 message from a specified developer-controlled wallet. Please note that not all the Dapps currently support Smart Contract Account (SCA), the difference between EOA and SCA can be found in the account types guide, and you can check the list of Dapps that support SCA: https://eip1271.io/.

      Parameters

      • input: SignMessageInput

      Returns Promise<TrimDataResponse<SignatureResponse>>

      const response = await client.signMessage({
        walletId: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        encodedByHex: false,
        message: 'I agree with this transfer',
        memo: 'Transfer USDC to Sam',
      })
      console.log(response.data?.signature)

    • Sign a transaction from a specific developer-controlled wallet. NOTE: This endpoint is only available for the following chains: SOL, SOL-DEVNET, NEAR, NEAR-TESTNET, EVM, EVM-TESTNET. Each chain defines its own standard, please refer to Signing APIs doc.

      Parameters

      • input: SignTransactionInput

      Returns Promise<TrimDataResponse<SignTransactionResponse>>

      const response = await client.signTransaction({
        walletId: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        rawTransaction: 'ZGVlcGFrcm...VkZHlndW1taQ==',
        memo: 'Transfer USDC to Sam',
      })
      console.log(response.data?.signature)

    • Sign the EIP-712 typed structured data from a specified developer-controlled wallet. Please note that not all the Dapps currently support Smart Contract Account (SCA), the difference between EOA and SCA can be found in the account types guide, and you can check the list of Dapps that support SCA: https://eip1271.io/.

      Parameters

      • input: SignTypedDataInput

      Returns Promise<TrimDataResponse<SignatureResponse>>

      const response = await client.signTypedData({
        walletId: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        data: '{ "types": { "Data": [{ "name": "dummy", "type": "string" }],}, "domain": { "name": "Test", "chainId": 1337 }, "primaryType": "Data", "message": { "dummy": "dummy" }}',
        memo: 'Transfer USDC to Sam',
      })
      console.log(response.data?.signature)

    Token Lookup

    • Fetches details of a specific token given its unique identifier.

      Every token in your network of wallets has a UUID associated with it, regardless of whether it's already recognized or was added as a monitored token.

      Parameters

      • __namedParameters: GetTokenInput

      Returns Promise<TrimDataResponse<TokenResponse>>

      const response = await client.getToken({
        id: 'uuid-token-id',
      })
      console.log(response.data?.token)

    Transactions

    • Accelerates a specified transaction from a developer-controlled wallet.

      Additional gas fees may be incurred.

      Parameters

      • input: AccelerateTransactionInput

      Returns Promise<TrimDataResponse<AccelerateTransactionForDeveloper>>

      const response = await client.accelerateTransaction({
        id: "transaction-id",
      })
      console.log(response.data?.id)

    • Cancels a specified transaction from a developer-controlled wallet. Gas fees may still be incurred.

      This is a best-effort operation, it won't be effective if the original transaction has already been processed by the blockchain.

      Parameters

      • input: CancelTransactionInput

      Returns Promise<TrimDataResponse<CancelTransactionForDeveloper>>

      const response = await client.cancelTransaction({
        id: "transaction-id",
      })
      console.log(response.data)

    • Creates a transaction which executes a smart contract. ABI parameters must be passed in the request. Related transactions may be submitted as a batch transaction in a single call.

      Parameters

      • input: CreateContractExecutionTransactionInput

      Returns Promise<TrimDataResponse<CreateContractExecutionTransactionForDeveloper>>

      const response = await client.createContractExecutionTransaction({
        amount: '0.01',
        abiFunctionSignature: 'burn(uint256)',
        contractAddress: '0xa51c9c604b79a0fadbfed35dd576ca1bce71da0a',
        walletId: 'a635d679-4207-4e37-b12e-766afb9b3892',
        fee: {
          type: 'level',
          config: {
            feeLevel: 'HIGH',
          },
        },
      })
      console.log(response.data)

    • Initiates an on-chain digital asset transfer from a specified developer-controlled wallet.

      Parameters

      • input: CreateTransferTransactionInput

      Returns Promise<TrimDataResponse<CreateTransferTransactionForDeveloperResponse>>

      const response = await client.createTransaction({
        amount: ['0.01'],
        destinationAddress: '0xa51c9c604b79a0fadbfed35dd576ca1bce71da0a',
        tokenId: '738c8a6d-8896-46d1-b2cb-083600c1c69b',
        walletId: 'a635d679-4207-4e37-b12e-766afb9b3892',
        fee: {
          type: 'level',
          config: {
            feeLevel: 'HIGH',
          },
        },
      })
      console.log(response.data)

    • Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain.

      Parameters

      • input: EstimateContractExecutionFeeInput

      Returns Promise<TrimDataResponse<EstimateTransactionFee>>

      const response = await client.estimateContractExecutionFee({
        abiFunctionSignature: 'burn(uint256)',
        abiParameters: [1000],
        contractAddress: '656d6fd6-d430-459c-9ba4-5c2074433f1b',
        source: {
          walletId: '9a014a34-4706-4e3f-879d-fc2a8764877c',
        },
      })
      console.log(response.data)

    • Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token.

      Parameters

      • input: EstimateTransferFeeInput

      Returns Promise<TrimDataResponse<EstimateTransactionFee>>

      const response = await client.estimateTransferFee({
        amount: ['0.01'],
        destinationAddress: '656d6fd6-d430-459c-9ba4-5c2074433f1b',
        tokenId: '9606f293-5b81-4970-acd3-c35c157461c2',
      })
      console.log(response.data)

    • Retrieves info for a single transaction using it's unique identifier.

      Parameters

      Returns Promise<TrimDataResponse<TransactionResponse>>

      const response = await client.getTransaction({
        id: '9fcb2e86-dec2-4226-81d1-4dbad429278c',
      })
      console.log(response.data?.transaction)

    • Lists all transactions. Includes details such as status, source/destination, and transaction hash.

      Parameters

      • Optionalinput: ListTransactionsInput

      Returns Promise<TrimDataResponse<Transactions>>

      const response = await client.listTransactions()
      console.log(response.data?.transactions)

    • Confirms that a specified address is valid for a given token on a certain blockchain.

      Parameters

      • input: ValidateAddressInput

      Returns Promise<TrimDataResponse<ValidateAddress>>

      const response = await client.validateAddress({
        address: '0xa95f8fafb3f6ae0f9ba7204eef07bde7a64cf2bc',
        blockchain: 'ETH-SEPOLIA',
      })
      console.log(response.data?.isValid)

    Wallet Sets

    • Create a developer controlled wallet set.

      Parameters

      Returns Promise<TrimDataResponse<WalletSetResponse>>

      const response = await client.createWalletSet({
        name: 'My first wallet set',
      })
      console.log(response.data?.walletSet)

    • Retrieve an existing wallet set.

      Parameters

      • input: GetWalletSetInput

      Returns Promise<TrimDataResponse<WalletSetResponse>>

      const response = await client.getWalletSet({
        id: 'd1daae42-6853-4d66-8184-65468e95225b',
      })
      console.log(response.data?.walletSet)

    • Retrieve a list of all wallet sets.

      Parameters

      • Optionalinput: ListWalletSetsInput

      Returns Promise<TrimDataResponse<WalletSets>>

      const response = await client.listWalletSets()
      console.log(response.data?.walletSets)

    • Update the name of the wallet set using its ID.

      Parameters

      • input: UpdateWalletSetInput

      Returns Promise<TrimDataResponse<WalletSetResponse>>

      const response = await client.updateWalletSet({
        id: 'b26bb9f9-7b85-48e2-a613-1923fb470e2e',
        name: 'My new walletSet name',
      })
      console.log(response.data?.walletSet)

    Wallets

    • Generates a new developer-controlled wallet or batch of wallets within a wallet set, specifying blockchain and wallet name.

      Parameters

      Returns Promise<TrimDataResponse<Wallets>>

      const response = await client.createWallets({
        blockchains: ["MATIC-AMOY"],
        count: 1,
        walletSetId: "67eb6eac-a7f5-4c04-9200-2fbf969426b0",
      })
      console.log(response.data?.wallets)

    • Derives an EOA wallet using the address of the specified wallet and blockchain. If the target wallet already exists, its metadata will be updated with the provided metadata.

      NOTE: This endpoint is only available for EVM-based wallets.

      Parameters

      Returns Promise<TrimDataResponse<WalletResponse>>

      const response = await client.deriveWallet({
        id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        blockchain: 'ETH',
      })
      console.log(response.data?.wallet)

    • Retrieve an existing wallet using its unique identifier.

      Parameters

      Returns Promise<TrimDataResponse<WalletResponse>>

      const response = await client.getWallet({
        id: '223d9a78-ca33-4cbd-ab83-8f083e3c045b',
      })
      console.log(response.data?.wallet)

    • Fetches the info for all NFTs stored in a single developer-controlled wallet, using the wallets unique identifier.

      Parameters

      • input: GetWalletNFTBalanceInput

      Returns Promise<TrimDataResponse<Nfts>>

      const response = await client.getWalletNFTBalance({
        id: 'b21c473f-8c93-4826-90f5-cad3cfeef4c1',
      })
      console.log(response.data?.nfts)

    • Retrieves a list of all wallets that fit the specified parameters, including native balances and USDC/EURC token balances if specified.

      NOTE: Balances update automatically with transfers or via the Get token balance for a wallet for accuracy.

      Parameters

      Returns Promise<TrimDataResponse<WalletsWithBalances>>

      const response = await client.getWalletsWithBalances({
       blockchain: 'ETH-SEPOLIA',
       amountGte: '1',
      })
      console.log(response.data?.wallets)

    • Fetches the digital asset balance for a single developer-controlled wallet using its unique identifier.

      Parameters

      • input: GetWalletTokenBalanceInput

      Returns Promise<TrimDataResponse<Balances>>

      const response = await client.getWalletTokenBalance({
        id: 'e518abf8-882d-4fa1-931e-596b28aa970b',
      })
      console.log(response.data?.tokenBalances)

    • Retrieves a list of all wallets that fit the specified parameters.

      Parameters

      Returns Promise<TrimDataResponse<Wallets>>

      const response = await client.listWallets()
      console.log(response.data?.wallets)

    • Update information for a specific wallet using its unique identifier.

      Parameters

      • input: UpdateWalletInput

      Returns Promise<TrimDataResponse<WalletResponse>>

      const response = await client.updateWallet({
        id: '1f29cce1-ab6c-41ad-84d8-9d223d014881',
        name: 'Updated name',
      })
      console.log(response.data?.wallet)

    Webhook Subscriptions

    • Create a notification subscription by configuring an endpoint to receive notifications.

      For details, see the Notification Flows guide.

      Parameters

      • input: CreateSubscriptionInput

      Returns Promise<TrimDataResponse<SubscriptionResponse>>

      const response = await client.createSubscription({
        endpoint: 'https://example.org/handler/for/notifications',
      })
      console.log(response)

    • Delete a notification subscription.

      Parameters

      • subscriptionId: string

      Returns Promise<AxiosResponse<void, any>>

      const response = await client.deleteSubscription('b3d9d2d5-4c12-4946-a09d-953e82fae2b0')
      console.log(response)

    • Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle. In the headers of each webhook, you can find

      1. X-Circle-Signature: a header containing the digital signature generated by Circle.
      2. X-Circle-Key-Id: a header containing the UUID. This is will be used as the ID as URL parameter to retrieve the relevant public key.

      Parameters

      • subscriptionId: string

      Returns Promise<TrimDataResponse<NotificationSignaturePublicKey>>

      const response = await client.getNotificationSignature('b3d9d2d5-4c12-4946-a09d-953e82fae2b0')
      console.log(response)

    • Retrieve an existing notification subscription.

      Parameters

      • subscriptionId: string

      Returns Promise<TrimDataResponse<SubscriptionResponse>>

      const response = await client.getSubscription('b3d9d2d5-4c12-4946-a09d-953e82fae2b0')
      console.log(response)

    • Retrieve an array of existing notification subscriptions.

      Returns Promise<TrimDataResponse<Subscriptions>>

      const response = await client.listSubscriptions()
      console.log(response)

    • Update subscription endpoint to receive notifications.

      Parameters

      • input: UpdateSubscriptionInput

      Returns Promise<TrimDataResponse<SubscriptionResponse>>

      const response = await client.updateSubscription({
        id: 'b3d9d2d5-4c12-4946-a09d-953e82fae2b0',
        name: 'payment-processor',
        enabled: true,
      })
      console.log(response)

    Settings

    Member Visibility

    On This Page

    Developer Account
    Faucet
    Monitored Tokens
    Other
    Signing
    Token Lookup
    Transactions
    Wallet Sets
    Wallets
    Webhook Subscriptions