---
title: "Borrow principal"
method: POST
path: "/markets/creditbook/borrow"
tags: ["creditbook"]
---

# Borrow principal

`POST /markets/creditbook/borrow`

Borrows additional principal against an existing loan and can optionally refinance the targeted ledger in the same transaction.

## Headers

- `Idempotent-Key` string, nullable

## Request body

- TxnBorrowPrincipalParams
  - `borrowParams` BorrowPrincipalParamsSchema, required — Params for borrowing principal against an existing loan (`borrow_principal`).
    - `amount` integer, required — Principal amount to borrow, in the principal mint's native units.
    - `assetIndexGuidance` integer[], required — Per-collateral oracle asset-index guidance.
    - `duration` integer, required — Index into the strategy's offered durations for this ledger.
    - `expectedLoanValues` ExpectedLoanValuesSchema, required — Expected loan economics the borrower signs off on, checked on-chain against the freshly-priced values to bound slippage.
      - `expectedApy` integer, required — Expected loan APY, in basis points of a hundredth (cbps).
      - `expectedLqt` integer[], required — Expected per-ledger liquidation threshold, one entry per ledger slot.
    - `skipSolUnwrap` boolean, required — When true, keep borrowed SOL wrapped instead of unwrapping to native SOL.
  - `isLoop` boolean, nullable
  - `loan` string, required — Loan account address (base58).
  - `refinanceParams` RefinanceLedgerParamsSchema — Params for refinancing a ledger to a new strategy/duration (`refinance_ledger`).
    - `assetIndexGuidance` integer[], required — Per-collateral oracle asset-index guidance.
    - `durationIndex` integer, required — Index into the new strategy's offered durations.
    - `ledgerIndex` integer, required — Index of the ledger being refinanced.
  - `strategy` string, required — Strategy account address (base58).
  - `weightMatrixUpdates` WeightMatrixUpdateParams[]
    - `collateralIndex` integer, required
    - `weightMatrixUpdate` integer[], required

## Response `200`

Serialized transaction for borrowing additional principal.

- LoanTxnResponse
  - `expectedLoanInfo` LoanInfo, required
    - `collateral` LoanCollateral[], required
      - `amount` integer, required
      - `assetIdentifier` string, required
      - `assetMint` string, required
      - `assetType` integer, required
      - `id` integer
      - `index` integer, required
      - `lastInteractedTime` integer
      - `lastInteractedTxn` string
      - `loan` string, required
      - `writeVersion` integer
    - `collateralYieldPct` number, double, required
    - `events` GenericParsedLoanEvent[]
      - `action` 'addCollateral' | 'removeCollateral' | 'borrowPrincipal' | 'repayPrincipal' | 'refinanceLedger' | 'sellLedger' | 'liquidate', required
      - `actionMetadata` union, required — API-specific representation of loan event metadata (adjacently-tagged: `{ "type": <action>, "params": <metadata> }`).
        - object
          - `type` 'addCollateral', required
        - object
          - `type` 'removeCollateral', required
        - object
          - `params` ParsedBorrowPrincipalMetadata, required
            - `postBorrowPrincipalLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
            - `preBorrowPrincipalLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
          - `type` 'borrowPrincipal', required
        - object
          - `params` ParsedRepayPrincipalMetadata, required
            - `postRepaymentPrincipalLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
            - `preRepaymentPrincipalLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
          - `type` 'repayPrincipal', required
        - object
          - `params` ParsedRefinanceLedgerMetadata, required
            - `postRefinanceLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
            - `preRefinanceLedgerState` ParsedEventLedger, required — Snapshot of a ledger's state captured in an event's before/after metadata.
              - …
          - `type` 'refinanceLedger', required
        - object
          - `params` ParsedSellLedgerMetadata, required
            - `buyer` string, required
            - `seller` string, required
          - `type` 'sellLedger', required
        - object
          - `params` ParsedLiquidateLedgerMetadata, required
            - `collateralTransfers` ParsedLiquidatedCollateralMetadata[], required
              - …
            - `isTimeBasedLiquidation` boolean, required
            - `ledgerIndex` integer, required
            - `liquidationFee` number, double, required
          - `type` 'liquidate', required
        - object
          - `params` ParsedMigrateLedgerMetadata, required
            - `lockboxAddr` string, required
          - `type` 'migrate', required
      - `amount` integer, required
      - `assetIdentifier` string, required
      - `assetMint` string, nullable
      - `eventTime` integer, required
      - `eventTxn` string, required
      - `id` integer, required
      - `loan` string, required
      - `newLender` string, nullable
      - `originalLender` string, nullable
      - `usdPrice` number, double, nullable
    - `ledgers` Ledger[], required
      - `apy` integer, required
      - `duration` integer, required
      - `durationType` integer, required
      - `endTime` integer, required
      - `id` integer
      - `interestOutstanding` integer, required
      - `interestPerSecond` number, double, required
      - `isLoop` integer
      - `lastInteractedTime` integer, required
      - `lastInteractedTxn` string, required
      - `lastInterestUpdatedTime` integer, required
      - `ledgerIndex` integer, required
      - `loan` string, required
      - `lqtRatios` integer[], required — Per-collateral liquidation thresholds (cbps), same index order as `weights`.
      - `ltvRatios` integer[], required — Per-collateral loan-to-value ratios (cbps), same index order as `weights`.
      - `marketInformation` string, required
      - `principalDue` integer, required
      - `principalMint` string, required
      - `principalRepaid` integer, required
      - `startTime` integer, required
      - `status` integer, required
      - `strategy` string, required
      - `weights` integer[], required — Weight matrix: per-collateral weight (cbps), indexed by the market's collateral map. Drives how each collateral backs this ledger's principal.
      - `writeVersion` integer
    - `loan` Loan, required
      - `address` string, required
      - `borrower` string, required
      - `bump` integer, required
      - `closed` boolean, required
      - `id` integer
      - `lastInteractedTime` integer, required
      - `lastInteractedTxn` string, required
      - `loanStatus` integer, required
      - `nonce` integer, required
      - `startTime` integer, required
      - `writeVersion` integer, required
    - `loanType` integer, required
    - `matrixUpdates` LoanMatrixEvent[]
      - `id` integer
      - `ledgerIndex` integer, required
      - `loan` string, required
      - `lqtRatios` integer[], required — Per-collateral liquidation thresholds (cbps) after this update.
      - `ltvRatios` integer[], required — Per-collateral loan-to-value ratios (cbps) after this update.
      - `timestamp` integer, required
      - `txnSignature` string, required
      - `weights` integer[], required — Weight matrix (per-collateral weight, cbps) after this update.
      - `writeVersion` integer, required
    - `pastLedgers` Ledger[]
      - `apy` integer, required
      - `duration` integer, required
      - `durationType` integer, required
      - `endTime` integer, required
      - `id` integer
      - `interestOutstanding` integer, required
      - `interestPerSecond` number, double, required
      - `isLoop` integer
      - `lastInteractedTime` integer, required
      - `lastInteractedTxn` string, required
      - `lastInterestUpdatedTime` integer, required
      - `ledgerIndex` integer, required
      - `loan` string, required
      - `lqtRatios` integer[], required — Per-collateral liquidation thresholds (cbps), same index order as `weights`.
      - `ltvRatios` integer[], required — Per-collateral loan-to-value ratios (cbps), same index order as `weights`.
      - `marketInformation` string, required
      - `principalDue` integer, required
      - `principalMint` string, required
      - `principalRepaid` integer, required
      - `startTime` integer, required
      - `status` integer, required
      - `strategy` string, required
      - `weights` integer[], required — Weight matrix: per-collateral weight (cbps), indexed by the market's collateral map. Drives how each collateral backs this ledger's principal.
      - `writeVersion` integer
    - `principalYieldPct` number, double, required
  - `transactions` VersionedTransactionReturn[], required — Built, ready-to-sign versioned transactions.
    - `message` string, required — serialized message
    - `signatures` VersionedTransactionSignature[], required — serialized signatures
      - `publicKey` string, required — serialized message
      - `signature` string, required — serialized signatures

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `409` — Idempotency-Key reused with a different request body
- `500` — Internal server error

---

[API](https://skmtc.dev/loopscale/apis/loopscale-api.md) · [All operations](https://skmtc.dev/loopscale/apis/loopscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/loopscale/loopscale-api/revisions/531f64dbe09c/schema)