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

# Request Loan

> Borrow against posted collateral — crypto, invoices, or inventory — with instant underwriting.

### Overview

A loan request posts collateral and asks for a principal against it. Underwriting is automated: the
response comes back with an approved amount, a rate, and a schedule rather than entering a queue.

The rate you're offered is a function of your **loan-to-value ratio**, not of the rate you request.
`requested_rate` is an input to negotiation, not a setting.

<Warning>
  Collateral is **liquidated** if your LTV breaches the maintenance threshold — the same mechanic as
  any collateralized position. Posting volatile collateral at a high `ltv_ratio` means a price move
  can trigger liquidation before a repayment is ever late. Over-collateralize deliberately.
</Warning>

### Body

<ParamField body="borrower_id" type="string" required>
  The borrower's [DID](/stateset-commerce-api-reference/dids), e.g.
  `did:stateset:borrower:def456`.
</ParamField>

<ParamField body="loan_amount" type="string" required>
  Principal requested, as a decimal string.
</ParamField>

<ParamField body="currency" type="string" required>
  `USDC` or `ssUSD`.
</ParamField>

<ParamField body="loan_purpose" type="string" required>
  Use of funds, e.g. `working_capital`. Feeds underwriting.
</ParamField>

<ParamField body="term_months" type="number" required>
  Term in months.
</ParamField>

<ParamField body="collateral" type="array" required>
  What secures the loan. Multiple assets of mixed type may be posted together; each carries its own
  LTV.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      `cryptocurrency`, `invoice`, or `inventory`.
    </ParamField>

    <ParamField body="asset" type="string">
      Ticker, for `cryptocurrency` collateral — e.g. `STATE`.
    </ParamField>

    <ParamField body="asset_id" type="string">
      Identifier, for asset-backed collateral — e.g. an invoice ID.
    </ParamField>

    <ParamField body="amount" type="string">
      Quantity posted, for fungible collateral.
    </ParamField>

    <ParamField body="current_value" type="string">
      Mark-to-market value.
    </ParamField>

    <ParamField body="face_value" type="string">
      Face value, for invoice collateral.
    </ParamField>

    <ParamField body="ltv_ratio" type="number">
      Advance rate against this asset — `0.5` lends 50% of its value. Liquid crypto carries a lower
      LTV than a receivable from an investment-grade buyer.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="requested_rate" type="number">
  Your target annual rate as a decimal — `0.08` is 8%. Indicative only.
</ParamField>

### Response

<ResponseField name="loan_id" type="string" required>
  Identifier for the loan.
</ResponseField>

<ResponseField name="status" type="string" required>
  `PENDING_APPROVAL`, `APPROVED`, `ACTIVE`, `REPAID`, or `LIQUIDATED`.
</ResponseField>

<ResponseField name="requested_amount" type="string" required>
  What you asked for.
</ResponseField>

<ResponseField name="approved_amount" type="string" required>
  What was approved. May be **less** than requested if collateral does not support the principal —
  compare the two before drawing down.
</ResponseField>

<ResponseField name="interest_rate" type="number" required>
  The rate actually applied.
</ResponseField>

<ResponseField name="term_months" type="number" required>
  Approved term.
</ResponseField>

<ResponseField name="monthly_payment" type="string" required>
  Scheduled payment.
</ResponseField>

<ResponseField name="total_collateral_value" type="string" required>
  Aggregate mark-to-market value of everything posted.
</ResponseField>

<ResponseField name="ltv_ratio" type="number" required>
  Realised LTV across the whole position — principal ÷ collateral value. Watch this, not the
  per-asset ratios.
</ResponseField>

<ResponseField name="approval_time" type="string" required>
  How long underwriting took, e.g. `instant`.
</ResponseField>

<ResponseField name="funds_available" type="string" required>
  When the principal can be drawn.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.stateset.com/v1/finance/loans/request' \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "borrower_id": "did:stateset:borrower:def456",
      "loan_amount": "25000.00",
      "currency": "USDC",
      "loan_purpose": "working_capital",
      "term_months": 12,
      "collateral": [
        {
          "type": "cryptocurrency",
          "asset": "STATE",
          "amount": "50000.00",
          "current_value": "50000.00",
          "ltv_ratio": 0.5
        },
        {
          "type": "invoice",
          "asset_id": "inv_78901",
          "face_value": "15000.00",
          "ltv_ratio": 0.8
        }
      ],
      "requested_rate": 0.08
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "loan_id": "loan_5z8nPq3oW7",
    "status": "PENDING_APPROVAL",
    "requested_amount": "25000.00",
    "approved_amount": "25000.00",
    "interest_rate": 0.075,
    "term_months": 12,
    "monthly_payment": "2256.50",
    "total_collateral_value": "65000.00",
    "ltv_ratio": 0.38,
    "approval_time": "instant",
    "funds_available": "2024-06-25T12:15:00Z"
  }
  ```
</ResponseExample>

### Next

Approval does not move money. Draw the principal with
`POST /v1/finance/loans/{loan_id}/drawdown`, which returns the full repayment schedule — see
[Finance](/stateset-commerce-api-reference/finance#loan-management).

### Related

* [Approve Loan](/stateset-commerce-api-reference/loans/approve)
* [Repay Loan](/stateset-commerce-api-reference/loans/repay)
* [Liquidate Loan](/stateset-commerce-api-reference/loans/liquidate)
* [Factor Invoice](/stateset-commerce-api-reference/invoices/factor) — sell a receivable instead of borrowing against it