Quickstart: Originate a loan

Borrow USDC against cirBTC collateral on Arc Testnet. This quickstart uses the Viem adapter.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22+.
Created an EVM wallet using a wallet provider such as MetaMask and added Arc Testnet as a network.
Funded your wallet with testnet cirBTC for collateral and testnet USDC for gas on Arc Testnet from the Circle Faucet.

Step 1. Set up the project

1.1. Create the project and install dependencies

Create a project directory, initialize a Node.js project with an ES module type and run scripts, then install runtime and dev dependencies:

Shell

mkdir app-kit-borrow-originate
cd app-kit-borrow-originate
npm init -y
npm pkg set type=module
npm pkg set scripts.explore-markets="tsx --env-file=.env explore-markets.ts"
npm pkg set scripts.borrow="tsx --env-file=.env borrow.ts"
npm install @circle-fin/app-kit @circle-fin/adapter-viem-v2 viem tsx
npm install --save-dev typescript @types/node

Only need Borrow and want a lighter install than the full App Kit? Install the standalone package instead: @circle-fin/borrow-kit

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file configured for ESM and Node:

Shell

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Create a .env file in the project directory and add it to your .gitignore. Open .env in your editor and add your wallet’s private key. Replace YOUR_PRIVATE_KEY with the private key of the wallet you funded with cirBTC:

.env

PRIVATE_KEY=YOUR_PRIVATE_KEY

Edit .env files in your IDE or editor so credentials are not leaked to your shell history.

Step 2. Explore available markets

kit.borrow.exploreMarkets returns the markets available on a blockchain along with each market’s collateral and loan tokens, borrow APY, LLTV, and liquidity. Use it to pick a market to borrow from.

2.1. Create the discovery script

Create an explore-markets.ts file:

explore-markets.ts

import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

async function main() {
  const { markets } = await kit.borrow.exploreMarkets({
    chain: "Arc_Testnet",
    sortBy: "borrowApy",
  });

  console.log(`Found ${markets.length} markets on this page`);
  console.dir(markets, { depth: null, colors: true });
}

void main();

2.2. Run the discovery script

In your terminal, run:

Shell

npm run explore-markets

You’ll see one or more markets with their marketId, borrowApy, lltv, and liquidity fields. Copy a marketId for the next step. To walk every matching market without paging through the results yourself, use kit.borrow.exploreMarketsIterator. It accepts the same filters as exploreMarkets and yields one market at a time:

TypeScript

for await (const market of kit.borrow.exploreMarketsIterator({
  chain: "Arc_Testnet",
  sortBy: "borrowApy",
})) {
  console.log(market.marketId, market.borrowApy);
}

Step 3. Open the loan

Each market allows one open loan per wallet at a time. If a loan is already open for the wallet in that market, opening a new one raises BORROW_LOAN_ALREADY_EXISTS with the existing loanId in the message.

3.1. Create the borrow script

Create a borrow.ts file. Replace YOUR_SELECTED_MARKET_ID with the market ID you copied. This script borrows 1,000 USDC against cirBTC:

borrow.ts

import { AppKit } from "@circle-fin/app-kit";
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2/next";

const kit = new AppKit();
const marketId = "YOUR_SELECTED_MARKET_ID";
const borrowAmount = "1000.0";

const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

async function main() {
  const result = await kit.borrow.borrow({
    from: { adapter, chain: "Arc_Testnet" },
    marketId,
    borrowAmount,
  });

  console.dir(result, { depth: null, colors: true });
}

void main();

3.2. Run the borrow script

In your terminal, run:

Shell

npm run borrow

On confirmation, the result includes the new loanId, the amountBorrowed, and a txHash.

Step 4. Manage the loan

Use the loan’s loanId to keep operating on it over time:

Add collateral or borrow more against the loan.
Pay down the loan with a partial repayment, full close, or collateral withdrawal.
Monitor the loan by reading its position or registering a webhook for health updates.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow

Quickstart: Originate a loan

Prerequisites

Step 1. Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Explore available markets

2.1. Create the discovery script

2.2. Run the discovery script

Step 3. Open the loan

3.1. Create the borrow script

3.2. Run the borrow script

Step 4. Manage the loan

​Prerequisites

​Step 1. Set up the project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​1.3. Set environment variables

​Step 2. Explore available markets

​2.1. Create the discovery script

​2.2. Run the discovery script

​Step 3. Open the loan

​3.1. Create the borrow script

​3.2. Run the borrow script

​Step 4. Manage the loan

Prerequisites

Step 1. Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Explore available markets

2.1. Create the discovery script

2.2. Run the discovery script

Step 3. Open the loan

3.1. Create the borrow script

3.2. Run the borrow script

Step 4. Manage the loan