> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build loan

> Builds or mutates a loan through a sequence of high-level actions. Supported step types currently include `repay`, `flashBorrow`, and `swapCollateral`.



## OpenAPI

````yaml post /markets/creditbook/build
openapi: 3.1.0
info:
  title: Loopscale API
  version: 0.1.0
servers:
  - url: https://tars.loopscale.com/v1
    description: Loopscale Production Server
security: []
paths:
  /markets/creditbook/build:
    post:
      tags:
        - creditbook
      summary: Build loan
      description: >-
        Builds or mutates a loan through a sequence of high-level actions.
        Supported step types currently include `repay`, `flashBorrow`, and
        `swapCollateral`.
      operationId: query_build_loan
      parameters:
        - name: Idempotent-Key
          in: header
          description: >-
            Optional idempotency key; a retried write with the same key replays
            the original response
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanBuildParams'
        required: true
      responses:
        '200':
          description: >-
            Derived loan address and the transaction sequence produced by the
            requested build steps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanBuildResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Idempotency-Key reused with a different request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LoanBuildParams:
      type: object
      required:
        - steps
      properties:
        loan:
          type:
            - string
            - 'null'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/LoanBuildStep'
          description: Ordered build steps.
    LoanBuildResponse:
      type: object
      required:
        - loan
        - transactions
      properties:
        loan:
          type: string
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/VersionedTransactionReturn'
    ErrorResponse:
      type: object
      description: |-
        Canonical error envelope for every endpoint. The `x-request-id` response
        header carries the correlation id for the failing request.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
          description: error detail
    LoanBuildStep:
      oneOf:
        - type: object
          required:
            - params
            - type
          properties:
            params:
              $ref: '#/components/schemas/TxnRepayPrincipalParams'
            type:
              type: string
              enum:
                - repay
        - type: object
          required:
            - params
            - type
          properties:
            params:
              $ref: '#/components/schemas/IncreaseLeverageTransactionInput'
            type:
              type: string
              enum:
                - flashBorrow
        - type: object
          required:
            - params
            - type
          properties:
            params:
              $ref: '#/components/schemas/TxnSwapCollateralParams'
            type:
              type: string
              enum:
                - swapCollateral
      description: |-
        One step of a composed loan build, adjacently-tagged by `type` with the
        step's own transaction params under `params`.
    VersionedTransactionReturn:
      type: object
      description: versioned txn return
      required:
        - message
        - signatures
      properties:
        message:
          type: string
          description: serialized message
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/VersionedTransactionSignature'
          description: serialized signatures
    ErrorDetails:
      type: object
      description: Inner detail of the [`ErrorResponse`] envelope.
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code, mirrored in the response status line
          example: 400
          minimum: 0
        message:
          type: string
          description: human-readable, client-safe message (sensitive data redacted)
          example: Request could not be processed.
    TxnRepayPrincipalParams:
      type: object
      required:
        - loan
        - repayParams
      properties:
        closeIfPossible:
          type: boolean
        collateralWithdrawalParams:
          type: array
          items:
            $ref: '#/components/schemas/WithdrawCollateralParams'
        cpiIxs:
          type: array
          items:
            $ref: '#/components/schemas/ParsedInstruction'
          description: Caller-supplied CPI instructions spliced into the built transaction.
        cpiLuts:
          type: array
          items:
            type: string
        cpiSigners:
          type: array
          items:
            type: string
        loan:
          type: string
        repayParams:
          type: array
          items:
            $ref: '#/components/schemas/RepayPrincipalParamsSchema'
        setupIxs:
          type: array
          items:
            $ref: '#/components/schemas/ParsedInstruction'
          description: Setup instructions run before the main instructions.
        setupLuts:
          type: array
          items:
            type: string
        setupSigners:
          type: array
          items:
            type: string
        stakeInstructions:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/StakeLpQueryParams'
              description: >-
                Optional vault LP stake leg to compose with this txn as a
                suffix.

                Used to stake collateral released by repayments.
        unifySetup:
          type: boolean
        weightMatrixUpdates:
          type: array
          items:
            $ref: '#/components/schemas/WeightMatrixUpdateParams'
    IncreaseLeverageTransactionInput:
      type: object
      required:
        - principalRequested
        - depositCollateral
      properties:
        cpiIxs:
          type: array
          items:
            $ref: '#/components/schemas/ParsedInstruction'
          description: Caller-supplied CPI instructions spliced into the built transaction.
        cpiLuts:
          type: array
          items:
            type: string
        cpiSigners:
          type: array
          items:
            type: string
        depositCollateral:
          type: array
          items:
            $ref: '#/components/schemas/DepositCollateralInput'
          description: Collateral to deposit alongside the borrow.
        isLoop:
          type:
            - boolean
            - 'null'
        loanAddress:
          type:
            - string
            - 'null'
        nonce:
          type:
            - string
            - 'null'
        principalRequested:
          type: array
          items:
            $ref: '#/components/schemas/BorrowPrincipalRequested'
          description: Per-ledger principal borrow requests.
        refinanceParams:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RefinanceLedgerParamsSchema'
              description: Optional on-chain refinance params.
        setupIxs:
          type: array
          items:
            $ref: '#/components/schemas/ParsedInstruction'
          description: Setup instructions run before the main instructions.
        setupLuts:
          type: array
          items:
            type: string
        setupSigners:
          type: array
          items:
            type: string
        unifySetup:
          type: boolean
    TxnSwapCollateralParams:
      type: object
      required:
        - loan
        - withdrawCollateral
        - depositCollateral
      properties:
        cpiIxs:
          type: array
          items:
            $ref: '#/components/schemas/ParsedInstruction'
          description: Caller-supplied CPI instructions spliced into the built transaction.
        cpiLuts:
          type: array
          items:
            type: string
        cpiSigners:
          type: array
          items:
            type: string
        depositCollateral:
          type: array
          items:
            $ref: '#/components/schemas/DepositCollateralInput'
        loan:
          type: string
        withdrawCollateral:
          type: array
          items:
            $ref: '#/components/schemas/WithdrawCollateralParams'
    VersionedTransactionSignature:
      type: object
      description: versioned txn return
      required:
        - publicKey
        - signature
      properties:
        publicKey:
          type: string
          description: serialized message
        signature:
          type: string
          description: serialized signatures
    WithdrawCollateralParams:
      type: object
      required:
        - collateralMint
        - amount
      properties:
        amount:
          type: integer
          format: int64
          minimum: 0
        closeIfEligible:
          type: boolean
        collateralMint:
          type: string
    ParsedInstruction:
      type: object
      description: >-
        A parsed Solana instruction (program id, ordered account metas, and
        base58

        instruction data) spliced verbatim into a built transaction as a CPI.
      required:
        - programId
        - accounts
        - data
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/ParsedAccountMeta'
          description: ordered account metas
        data:
          type: string
          description: base58-encoded instruction data
        programId:
          type: string
          description: program id (base58)
    RepayPrincipalParamsSchema:
      type: object
      description: Params for repaying principal on a ledger (`repay_principal`).
      required:
        - amount
        - ledgerIndex
        - repayAll
      properties:
        amount:
          type: integer
          format: int64
          description: >-
            Amount to repay, in the principal mint's native units (ignored if
            `repay_all`).
          minimum: 0
        ledgerIndex:
          type: integer
          format: int32
          description: Index of the ledger being repaid.
          minimum: 0
        repayAll:
          type: boolean
          description: Repay the ledger's full outstanding principal + interest.
    StakeLpQueryParams:
      type: object
      required:
        - vault
        - amount
      properties:
        amount:
          type: integer
          format: int64
          minimum: 0
        stakeAccount:
          type:
            - string
            - 'null'
        vault:
          type: string
    WeightMatrixUpdateParams:
      type: object
      required:
        - weightMatrixUpdate
        - collateralIndex
      properties:
        collateralIndex:
          type: integer
          format: int32
          minimum: 0
        weightMatrixUpdate:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
    DepositCollateralInput:
      type: object
      required:
        - collateralAmount
        - collateralAssetData
      properties:
        collateralAmount:
          type: integer
          format: int64
          minimum: 0
        collateralAssetData:
          $ref: '#/components/schemas/AssetDataInfo'
        loanCreationParams:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/LoanCreationParams'
        weightMatrixUpdate:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
    BorrowPrincipalRequested:
      type: object
      required:
        - ledgerIndex
        - principalAmount
        - principalMint
        - strategy
        - durationIndex
        - expectedLoanValues
      properties:
        durationIndex:
          type: integer
          format: int32
          minimum: 0
        expectedLoanValues:
          $ref: '#/components/schemas/ExpectedLoanValuesSchema'
        ledgerIndex:
          type: integer
          format: int32
          minimum: 0
        principalAmount:
          type: integer
          format: int64
          minimum: 0
        principalMint:
          type: string
        strategy:
          type: string
    RefinanceLedgerParamsSchema:
      type: object
      description: >-
        Params for refinancing a ledger to a new strategy/duration
        (`refinance_ledger`).
      required:
        - ledgerIndex
        - durationIndex
        - assetIndexGuidance
      properties:
        assetIndexGuidance:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
          description: Per-collateral oracle asset-index guidance.
        durationIndex:
          type: integer
          format: int32
          description: Index into the new strategy's offered durations.
          minimum: 0
        ledgerIndex:
          type: integer
          format: int32
          description: Index of the ledger being refinanced.
          minimum: 0
    ParsedAccountMeta:
      type: object
      description: One account reference of a parsed Solana instruction.
      required:
        - pubkey
        - isSigner
        - isWritable
      properties:
        isSigner:
          type: boolean
          description: whether the account must sign
        isWritable:
          type: boolean
          description: whether the account is written
        pubkey:
          type: string
          description: account pubkey (base58)
    AssetDataInfo:
      oneOf:
        - type: object
          required:
            - Spl
          properties:
            Spl:
              $ref: '#/components/schemas/SplData'
        - type: object
          required:
            - StakedSol
          properties:
            StakedSol:
              $ref: '#/components/schemas/StakedSolData'
        - type: object
          required:
            - Orca
          properties:
            Orca:
              $ref: '#/components/schemas/OrcaPositionData'
        - type: object
          required:
            - Meteora
          properties:
            Meteora:
              $ref: '#/components/schemas/MeteoraDlmmPositionData'
        - type: object
          required:
            - Raydium
          properties:
            Raydium:
              $ref: '#/components/schemas/RaydiumPositionData'
      description: |-
        Collateral asset identification, tagged by collateral kind (SPL token,
        staked SOL, or a CLMM LP position on Orca / Meteora / Raydium).
    LoanCreationParams:
      oneOf:
        - type: string
          enum:
            - Default
        - type: object
          required:
            - OrcaPositionCreate
          properties:
            OrcaPositionCreate:
              $ref: '#/components/schemas/OrcaPositionCreateParams'
      description: >-
        Optional collateral-specific loan-creation params (e.g. opening an Orca
        CLMM

        position as collateral); `Default` for a plain loan.
    ExpectedLoanValuesSchema:
      type: object
      description: >-
        Expected loan economics the borrower signs off on, checked on-chain
        against the

        freshly-priced values to bound slippage.
      required:
        - expectedApy
        - expectedLqt
      properties:
        expectedApy:
          type: integer
          format: int64
          description: Expected loan APY, in basis points of a hundredth (cbps).
          minimum: 0
        expectedLqt:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
          description: >-
            Expected per-ledger liquidation threshold, one entry per ledger
            slot.
    SplData:
      type: object
      required:
        - mint
      properties:
        mint:
          type: string
    StakedSolData:
      type: object
      required:
        - stakeAccount
        - stakePool
      properties:
        stakeAccount:
          type: string
        stakePool:
          type: string
    OrcaPositionData:
      type: object
      required:
        - positionMint
        - whirlpool
      properties:
        positionMint:
          type: string
        tokenProgram:
          type:
            - string
            - 'null'
        whirlpool:
          type: string
    MeteoraDlmmPositionData:
      type: object
      required:
        - positionAddress
        - lbPair
      properties:
        lbPair:
          type: string
        positionAddress:
          type: string
        tokenProgram:
          type:
            - string
            - 'null'
    RaydiumPositionData:
      type: object
      required:
        - mint
        - pool
      properties:
        mint:
          type: string
        pool:
          type: string
        tokenProgram:
          type:
            - string
            - 'null'
    OrcaPositionCreateParams:
      type: object
      required:
        - upperTick
        - lowerTick
        - tickSpacing
        - whirlpool
        - tokenMintA
        - tokenMintB
      properties:
        lowerTick:
          type: integer
          format: int32
        tickSpacing:
          type: integer
          format: int32
        tokenMintA:
          type: string
        tokenMintB:
          type: string
        upperTick:
          type: integer
          format: int32
        whirlpool:
          type: string

````