Borrow SDK

Access is gated to approved partners - reach out to the Surge team for a read-only npm token and test credentials. The shapes below match the shipped v0.1.

The SDK is headless and signer-agnostic: it never holds keys, renders no UI, and runs in the browser, Node, and React Native. You bring a Bitcoin taproot signer, an EVM signer, and a storage adapter; the SDK builds each intent, calls your signer, and talks to the Surge relayer.

Scope: BTC collateral in a per-user taproot vault, USDC on Base (6 decimals), variable + fixed markets, and the full lifecycle - deposit + initial borrow, add collateral, borrow more, repay, extend, withdraw - on signet + Base Sepolia (test) and Bitcoin mainnet + Base (production).

How it works

1. Session. The user signs one Sign-In-with-Ethereum message and a session JWT is issued (persisted via your storage adapter, reused across restarts). The Bitcoin key comes from your btcSigner. There is no Bitcoin signature at login - the withdraw PSBT is the only one in the whole flow.
2. Vault. The SDK derives the taproot deposit address locally from the user's key.
3. Deposit + borrow. One signed intent covers collateral + initial borrow. The user sends BTC to the vault from any wallet; once it confirms, Surge opens the position on Base and USDC lands at the user's EVM address.
4. Manage. Read collateral, debt, LTV and rate; borrow more, repay and withdraw, extend the term, and pull BTC back out.

Every action is a single await - inject the two signers once, and the SDK handles build → sign → submit inside each call. Almost every action takes a positionId (see Position ID).

Install and configure

// npm install @surgecredit/borrow-sdk viem
import { createBorrowClient } from "@surgecredit/borrow-sdk";
 
const client = createBorrowClient({
  network: "signet", // "signet" | "mainnet"
  storage: window.localStorage, // optional in the browser; see below
  // evmRpcUrl / btcApiUrl are optional - omit to use the network's public defaults
});

• network - "signet" (Bitcoin signet + Base Sepolia) or "mainnet" (Bitcoin mainnet + Base).
• evmRpcUrl / btcApiUrl - optional. Omitted, they fall back to public defaults (which rate-limit - pass your own for production). The relayer API, Surge price oracle, and Supabase project are fixed per network and not configurable.
• storage - where the session token is kept so users don't re-sign in on every restart. Optional in the browser (falls back to localStorage); required on React Native and Node.

interface StorageAdapter {
  getItem(key: string): string | null | Promise<string | null>;
  setItem(key: string, value: string): void | Promise<void>;
  removeItem(key: string): void | Promise<void>;
}

On React Native use a secure store (encrypted at rest), not plaintext AsyncStorage. Don't pass sessionStorage - it clears on close, logging the user out every restart.

viem is the only peer dependency; the core client has no framework dependencies.

Signers

Two small interfaces, both required. BtcSigner is satisfied by anything that can Schnorr-sign a PSBT; EvmSigner by anything that signs EIP-191/EIP-712. A key you derive yourself, a wallet SDK, or a server-side signer all work the same way - the SDK never holds keys and doesn't care where the signature comes from.

interface BtcSigner {
  address: string;
  publicKey: string; // x-only taproot pubkey (32-byte hex)
  signPsbt(psbtBase64: string, inputs: TapInputRef[]): Promise<string>;
}
 
interface EvmSigner {
  address: `0x${string}`;
  signMessage(message: string): Promise<`0x${string}`>;      // EIP-191
  signTypedData(data: Eip712TypedData): Promise<`0x${string}`>; // EIP-712
}

Address types: the user's Bitcoin key must be taproot; the deposit can be funded from any wallet or address type; withdrawals pay out to any address (P2TR, SegWit, or legacy). Reference signer adapters (MetaMask, Unisat, mnemonic) ship in the SDK's examples/playground.

Session

const session = await client.createSession({ evmSigner, btcSigner });
// SIWE login (one EVM signature) -> JWT, persisted and resumable.
 
session.evmAddress;    // 0x…
session.btcPublicKey;  // x-only hex
 
// First-time users register a relayer profile (idempotent to check):
if (!(await session.userExists())) await session.registerUser();

Vault

const vault = session.getVault(); // local derivation, no network call
// { vaultId, depositAddress, scriptTree, network, exitTimelockBlocks }

Position ID

A credit line is identified by its Position ID (the position NFT). Get it once a line is open and pass it to every action:

const positionId = await session.getPositionId(); // string | null (null until open)

Deposit and first borrow

The first borrow is bundled with the deposit - there's no standalone borrow call. List markets, size the collateral with getRequiredCollateral, then create the deposit:

The minimum borrow is $5 (MIN_BORROW_USD) — that's the only floor on opening a line; there's no minimum on the deposit itself. createDeposit rejects less before prompting for a signature.

const markets = await session.getMarkets();
// [{ marketId, kind: "variable" | "fixed", borrowRateApr,
//    maxLtvBps, liquidationThresholdBps, active }]
 
const { requiredSats } = await session.getRequiredCollateral({
  marketId: markets[0].marketId,
  amountUsd: "1000",
});
 
const { depositId, vaultAddress } = await session.createDeposit({
  collateralSats: requiredSats,
  borrowAmountUsd: "1000",
  marketId: markets[0].marketId,
  durationDays: 90,
});
// show vaultAddress + QR; the user sends BTC from any wallet.
 
const stop = session.watchDeposit(depositId, (s) => {
  // s.status advances; s.nft_id is set once the position mints
  if (s.nft_id) stop();
});

On confirmation Surge opens the position and USDC is disbursed to the session's EVM address - confirm it landed with getUsdcBalance():

const { usd } = await session.getUsdcBalance(); // { raw, usd, owner, tokenAddress }

Use getDepositStatus(depositId) for a one-shot status check, or getActiveDeposit() to find and resume a pending deposit after a reload (it looks the wallet's deposit up by EVM address).

Read the position

const position = await session.getPosition(positionId);
// { positionId, isActive, marketId, collateralSats, debtUsd, principalUsd,
//   interestUsd, ltvPercent, maxBorrowUsd, collateralValueUsd, debtValueUsd,
//   maxLtvBps, loanExpiresAt, expired, exitBlock }
 
const quote = await session.getBorrowQuote({ marketId, amountUsd: "500" });
// { marketId, amountUsd, borrowRateApr, maxLtvBps }

Debt accrues at the position's market rate. Statuses are absolute data (amounts, timestamps, block heights), so a UI re-rendering from history always derives current state correctly.

Add collateral

Send more BTC to the same vault address, then sync it in. No signature - it's a relayer-side reconcile.

await session.addCollateral({ positionId });
// { positionId, status, confirmedSats, onchainSats, unconfirmedSats }
session.watchCollateralSync(positionId, (u) => {/* watching -> success */});

Adding collateral raises maxBorrowUsd. Use syncCollateral(positionId) to reconcile any drift on load.

Borrow more

await session.borrowMore({ positionId, amountUsd: "250" }); // { positionId, txHash }

Pre-checked against the live LTV before the wallet is prompted - a draw over the max fails with LTV_EXCEEDED first.

To decide which call to make, quote it first: getRequiredCollateral({ marketId, amountUsd, positionId }) returns requiredSats: 0n when the position already has enough - draw with borrowMore. Otherwise send requiredSats more BTC to the vault and use borrowMoreSync({ positionId, amountUsd }) + watchBorrowMoreSync(...), which draws and syncs the new collateral in one flow.

Re-borrowing after full repayment

While a loan is active, the position is locked to its market. Once it's fully repaid (debt is 0), it no longer carries an active market, so the user can pick a new one before drawing again. Switch the market first, then borrow:

// only valid on a zero-debt position; the relayer rejects it while a loan is active
await session.switchMarket({ positionId, marketId }); // { positionId, marketId, confirmed }
await session.borrowMore({ positionId, amountUsd: "250" });

switchMarket writes the chosen market to the position on-chain and confirms it before returning, so the subsequent draw uses the new market. Drive your UI from the position's debt: show a market picker when debtUsd is 0, and lock it to the current market otherwise.

Repay

The user signs two EIP-712 payloads (repay authorization + USDC EIP-3009 transfer) and Surge relays the transaction. Overpayment is capped to the live debt.

await session.repay({ positionId, amountUsd: "200" }); // { txHash }

Withdraw BTC

Two signatures: an EIP-712 authorization (relayed by Surge) and a PSBT signature (the vault repayment path is a 2-of-2 between the user and the Surge key, which co-signs after validating the request).

const { medium } = await session.getFeeRates();      // { fast, medium, slow } sat/vB
const { txid } = await session.withdraw({
  positionId,
  toBtcAddress,
  amountSats: 200_000n,
  sendAll: false,   // true sweeps the whole vault
  feeRate: medium,  // omit to auto-fetch a ~3-block rate
});
// { txid, resumed, withdrawnSats }
 
session.watchWithdrawal(positionId, (u) => {/* … -> finalized | failed | expired */});

toBtcAddress is validated before any signature — empty, malformed, wrong-network, and the user's own vault address all throw INVALID_WITHDRAW_ADDRESS up front, so a doomed destination never costs a signature or leaves a pending withdrawal behind. Guard the vault case in your UI too: it's a valid Bitcoin tx, so nothing downstream would reject it — the vault would pay itself, the collateral never leaves, and the miner fee is burned.

Before prompting btcSigner.signPsbt, the SDK verifies the PSBT (outputs, amounts, change back to the vault). If a withdrawal is left unfinalized, getPendingWithdrawal(positionId) detects it and resumeWithdrawal(...) completes the Bitcoin leg without a fresh EVM signature.

Extend the credit line

Refresh the term on an open position without repaying; debt and collateral carry over.

await session.extendCreditLine({ positionId }); // { evmTxHash?, btcTxid, alreadyPending }
session.watchExtension(positionId, (u) => {/* … -> confirmed | finalized */});

Throws EXTENSION_ALREADY_PENDING if one is already in flight. Drive the renewal prompt from position.loanExpiresAt, not a stored flag.

Live activities

A position's ongoing credit-line events - the same feed the app shows in its header. Each activity carries a coarse state and a ready-made label.

const activities = await session.getActivities(positionId);
// [{ eventName, status, state: "in_progress" | "succeeded" | "failed", label }]
 
const stop = session.watchActivities(positionId, (activities) => {
  // full list each tick; polls ~30s; auto-stops when all terminal
});

eventName is one of sync_collateral, borrow_more, withdrawal, credit_line_extension.

Utilities

Helpers for wiring up your UI. None are required - they're conveniences so you don't re-derive protocol maths.

const q = await client.getRequiredCollateral({ marketId: 1, amountUsd: "10", positionId });
q.collateralValueUsd      // "14.29"  total needed: (debt + 10) / maxLtv
q.existingCollateralUsd   // "5.00"   already in the vault
q.additionalCollateralUsd // "9.29"   the gap
q.requiredSats            // 10472n   <- send this

Max LTV is per-market, so marketId decides the answer - the same $10 needs ~1/8 more collateral at 70% LTV than at 80%. For a fully-repaid position you intend to switch, pass the target market; while debt is live the market is locked and quoting a different one throws.

What your signers sign

Every watch* returns an unsubscribe fn - call it on unmount to stop polling.

Reads, addCollateral, syncCollateral, and switchMarket need no signature (the session JWT authorizes them).

Liquidation

Liquidation is settled by Surge and cannot be user-driven: the vault's liquidation leaf is a single-sig path spendable by Surge alone, and there's no relayer route. There is nothing to do - only state to read, and actions the SDK refuses.

const { inLiquidation, liquidated, type, at } = await session.getLiquidation(positionId);

isActive: false does not mean liquidated - it's equally true of a position that was simply repaid and closed. getLiquidation is what tells them apart. Position.inLiquidation carries the live flag if you already have the position.

Errors

Every flow throws a typed BorrowError with a stable .code (plus .status and .details). Branch on .code, never on the message.

Pre-flight validation runs before the SDK calls your signer, so the wallet is never prompted for an action that will fail.

Gating. Every mutating call first checks the position can actually take it, and throws rather than prompting. Liquidation is checked always and reported first - the collateral is already being taken, so it outranks every other state. Whether the position is still live, a pending withdrawal, and market liquidity are checked where they apply: a pending withdrawal blocks extendCreditLine (both spend the same vault UTXOs) but not repay, since repaying is how a holder de-risks. You don't have to pre-check to be safe - reading the state is how you avoid offering an action that will throw.

When a position ends. position.isActive is the actionability signal: it goes false when the term ends, when the line is repaid and closed, or when a liquidation settles. Drawing against any of those is refused; repay, withdraw, and extendCreditLine stay open, because renewing is the way out. Whether you get POSITION_EXPIRED or POSITION_CLOSED depends on whether collateral remains to renew against.

Catching the code is enough to be safe, but the throw is a backstop rather than a UI. To avoid offering an action that will throw, read the state first:

const p = await client.getPosition(positionId);
 
if (p.inLiquidation) {
  // Nothing to do - the collateral is being seized. client.getLiquidation() for detail.
} else if (p.isActive) {
  // Live: draw / repay / withdraw as normal.
} else if (p.collateralSats > 0n) {
  await client.extendCreditLine({ positionId }); // renew the term, collateral intact
} else {
  // Closed with nothing left - open a new credit line with createDeposit().
}

isActive tells you it's over; collateralSats tells you which remedy. Check inLiquidation first - it can be true on a still-active position, and it outranks everything.

Don't gate on position.expired - it reports term status (has loanExpiresAt passed), not usability. The two come apart in both directions: a position can be past its term and still fully live, and a settled one keeps a future expiry date while being dead. Use expired to warn about a lapsing term; use isActive to decide what's allowed.

Testing on signet

Integrate against signet first. Signet BTC is free from public faucets, and testnet USDC lives on Base Sepolia (the Circle faucet at faucet.circle.com covers it). A full lifecycle on signet - deposit through withdraw - is the acceptance bar before mainnet access. Note the Surge app is mainnet-only, so for signet you verify against the SDK itself rather than the app.