Borrow Service Provider

Borrow Service Provider defines the provider contract used by Borrow Kit and ships the default HTTP implementation for Circle's Borrow Service, covering loan listing (getLoans), partial repayment (repay, getRepayQuote), loan position reads (getPosition), collateral management (addCollateral, withdrawCollateral), reward claiming (claimRewards, getRewards), and registerWebhook.

registerWebhook builds the EIP-712 WebhookRegistration typed data, obtains a signature via the connected adapter, and submits the signed registration for verification (including EIP-1271 support for smart contract accounts). This is a permissionless, client-signed flow with no on-chain transaction and no API key.

Health-band notifications sent to the registered URL are delivered at-least-once: the same crossing can arrive more than once. Deduplicate on the notification's event_id, which is stable across redeliveries of one crossing.

Installation

npm install @circle-fin/provider-borrow-service
# or
yarn add @circle-fin/provider-borrow-service

This provider is included by default in @circle-fin/borrow-kit. Import it directly when you need to customize provider construction or compose your own Borrow Kit context.

Quick Start

Note: @circle-fin/borrow-kit is not yet published — this example shows the intended usage once it ships. Until then, construct BorrowServiceProvider and call registerWebhook on it directly with a resolved EVMChainDefinition; see Configuration below.

import {
  createBorrowKitContext,
  registerWebhook,
} from "@circle-fin/borrow-kit";
import { BorrowServiceProvider } from "@circle-fin/provider-borrow-service";
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";

const provider = new BorrowServiceProvider();
const context = createBorrowKitContext({ providers: [provider] });
const privateKey = process.env.PRIVATE_KEY;
if (!privateKey) throw new Error("PRIVATE_KEY is required");
const adapter = createViemAdapterFromPrivateKey({ privateKey });

const result = await registerWebhook(context, {
  from: { adapter, chain: "Arc_Testnet" },
  loanId: "11111111-1111-4111-8111-111111111111",
  webhookUrl: "https://example.com/webhook",
});

console.log(`Registered webhook: ${result.webhookUrl}`);

Configuration

BorrowServiceProvider accepts default configuration in the constructor and per-operation configuration on each request. Per-operation values take precedence, while omitted values continue to use constructor defaults.

An API key is optional only for borrow and getBorrowQuote, and required for getIntegratorConfig and setIntegratorConfig. Every other API rejects a configured key before making a request (or, for registerWebhook, before signing).

const provider = new BorrowServiceProvider({
  apiKey: process.env.CIRCLE_API_KEY,
  baseUrl: "https://api-staging.circle.com",
});

apiKey takes a Circle API key (<ENV>_API_KEY:<keyId>:<keySecret>). A legacy KIT_KEY:<keyId>:<keySecret> value goes in the same field and still authenticates; the console no longer issues them. It is a server-only secret and is refused in a browser. Omit it for keyless routes.

Calling registerWebhook directly on the provider requires a resolved EVMChainDefinition and the connected wallet's address in addition to the adapter. EVMChainDefinition values (such as ArcTestnet) currently live in the internal @core/chains package, which is not published standalone — the snippet below illustrates the shape expected until @circle-fin/borrow-kit (which resolves chains by name, as shown in Quick Start) is published:

import { ArcTestnet } from "@core/chains";

const result = await provider.registerWebhook({
  adapter,
  chain: ArcTestnet,
  address: "0x1234567890123456789012345678901234567890",
  loanId: "11111111-1111-4111-8111-111111111111",
  webhookUrl: "https://example.com/webhook",
  deadline: Math.floor(Date.now() / 1000) + 300,
});

console.log(`Registered webhook: ${result.webhookUrl}`);

The BorrowServiceProvider implements wallet-scoped loan listing through GET /v1/borrowKit/loans, including cursor pagination, response validation, retry behavior, and structured errors.

It also implements the partial-repayment and full-close prepare/quote endpoints. Repay requests reuse a caller-provided idempotency key or generate one when omitted; full-close writes generate one. Quote requests remain side-effect free and omit it.

License

This project is licensed under the Apache 2.0 License. Contact support for details.