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

# Set Reserve Ratio

> Hold a share of the pool back from borrowing as an exit buffer

Builds the `setReserveRatio` transaction that earmarks a share of the market's total liquidity against borrowing. Requires `ISSUER_ROLE` on the market, held by the wallet the lender of record named at adoption. The market brings its interest accrual up to date before the new ratio applies.

The reserve binds borrowing only. A withdrawal can always consume it, because a reserve that trapped a provider's money would be the opposite failure from the one it prevents. It is a buffer, not a guarantee: it serves whichever provider exits first. The slice held back is not lent and earns no interest, a cost the lender of record should disclose to liquidity providers.

The ratio applies at once to what a new borrow can draw, shown as `borrowableLiquidity` on [Get Exit Liquidity](/endpoints/lending/get-exit-liquidity). It moves no open loan. When withdrawals have used the reserve up, repayments refill it before any new borrow can draw again.

## Path Parameters

<ParamField path="marketId" type="string" required>Market ID.</ParamField>

## Body Parameters

<ParamField body="reserveRatioBps" type="integer" required>
  Share of total liquidity held back from borrowing, in basis points. Integer, 0 to 5000. The contract refuses anything above 50 percent. `0` clears the reserve, and every unit of unlent liquidity becomes borrowable again.
</ParamField>

<ParamField body="txHash" type="string">
  Hash of the transaction you broadcast for this operation. Send it to confirm the transaction and record the result. Omit it to receive the calldata. When `txHash` is present, every other field is ignored.
</ParamField>

## Confirm the Change

Send the mined hash back to this path as `{ "txHash": "0x..." }`. The API checks that the transaction called `setReserveRatio` on the market. It then reads the offering back from the chain and updates the market record.

## Response Fields

The calldata response carries the transaction twice. `transaction` holds `to` and `data`. The same `to` and `data` also sit directly on `data`, and that is where the `chainId` and `value` binding lands, so sign from those four fields.

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="action" type="string">`SIGN_TRANSACTION`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="transaction" type="object">`{ to, data }` for the `setReserveRatio` call on the market. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="to" type="string">The market address. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="data" type="string">The encoded `setReserveRatio` call. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="value" type="string">Always `"0"`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="chainId" type="integer">The chain your instance resolves to. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="functionName" type="string">`setReserveRatio`, or the verified function when confirming.</ResponseField>
    <ResponseField name="requiredRole" type="string">`ISSUER_ROLE`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="description" type="string">Plain-language summary of the change, including its cost to liquidity providers. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="requiredSigner" type="string">Always `null` here: the signer is whoever holds `ISSUER_ROLE`, not one fixed address. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="heldByThisInstance" type="boolean">`true` when a verified wallet of your instance holds `ISSUER_ROLE`, `false` when none does, `null` when the check could not be completed. The build is never refused on it. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="signerAddress" type="string">The wallet of your instance that holds `ISSUER_ROLE`, or `null`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="note" type="string">What to do when your instance cannot sign: the wallet the lender of record placed the role with must sign, because any other wallet reverts `NotAuthorized`. `null` when your instance can sign. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="confirmWith" type="object">`{ endpoint, field }`: the call that confirms this transaction, and the body field that carries the hash. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="txHash" type="string">Transaction hash. Returned when confirming.</ResponseField>
    <ResponseField name="signedBy" type="string">The wallet that sent the transaction. Returned when confirming.</ResponseField>
    <ResponseField name="blockNumber" type="integer">Block the transaction was mined in. Returned when confirming.</ResponseField>
    <ResponseField name="offering" type="object">The market's rate and term offering, read back from the chain after the transaction, with `reserveRatio` among its fields. The same object [Set Rate Mode](/endpoints/lending/set-rate-mode) returns. Returned when confirming.</ResponseField>
    <ResponseField name="updatedColumns" type="array">Names of the stored market fields this confirmation changed. Returned when confirming.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/markets/{marketId}/reserve-ratio" \
    -H "X-API-Key: trusset_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{ "reserveRatioBps": 500 }'
  ```

  ```typescript TypeScript theme={null}
  const url = `https://api.trusset.org/lending-external-securities-v2/api/markets/${marketId}/reserve-ratio`;
  const headers = { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' };

  const build = await fetch(url, { method: 'POST', headers, body: JSON.stringify({ reserveRatioBps: 500 }) });
  const { data: calldata } = await build.json();

  const tx = await issuerWallet.sendTransaction({
    to: calldata.to,
    data: calldata.data,
    value: calldata.value,
    chainId: calldata.chainId
  });
  await tx.wait();

  const confirm = await fetch(url, { method: 'POST', headers, body: JSON.stringify({ txHash: tx.hash }) });
  const { data } = await confirm.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Calldata Response theme={null}
  {
    "success": true,
    "data": {
      "action": "SIGN_TRANSACTION",
      "transaction": {
        "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
        "data": "0x..."
      },
      "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "data": "0x...",
      "functionName": "setReserveRatio",
      "requiredRole": "ISSUER_ROLE",
      "requiredSigner": null,
      "heldByThisInstance": true,
      "signerAddress": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
      "note": null,
      "confirmWith": {
        "endpoint": "POST /lending-external-securities-v2/api/markets/clx_secmarket_001/reserve-ratio",
        "field": "txHash"
      },
      "chainId": 11155111,
      "value": "0"
    }
  }
  ```

  ```json Confirmed Response theme={null}
  {
    "success": true,
    "data": {
      "txHash": "0x55635f4de8ec6649d2b3a78b49a449a99e9e31e1270fe3add4bcf9f71224bfb4",
      "functionName": "setReserveRatio",
      "signedBy": "0x5ad87a0621175206b72d10e4b8577b192e7f40ab",
      "blockNumber": 6789012,
      "offering": {
        "maxLoanDuration": "15552000",
        "termGracePeriod": "259200",
        "terminalDueDate": null,
        "termPenalty": "200",
        "marketDueFloor": null,
        "allowExtension": true,
        "rateMode": "CURVE",
        "rateFloor": "0",
        "rateCap": "0",
        "maxFixedRate": null,
        "reserveRatio": "500",
        "operatorShare": "800"
      },
      "updatedColumns": ["reserveRatio"]
    }
  }
  ```

  ```json Error - Above the Cap theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request parameters",
      "details": [
        { "field": "reserveRatioBps", "message": "The market contract caps the reserve ratio at 5000 bps (50% of total liquidity)" }
      ]
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                     | HTTP  | Cause                                                                                                        |
| ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------ |
| `MISSING_MARKET_ID`      | `400` | The `marketId` path segment is longer than 100 characters                                                    |
| `VALIDATION_ERROR`       | `400` | `reserveRatioBps` is missing, not an integer, or outside 0 to 5000, or `txHash` is malformed                 |
| `INVALID_CONFIRMATION`   | `400` | The market has no on-chain address, so there is nothing to confirm against                                   |
| `MARKET_NOT_FOUND`       | `404` | No market with this ID on your instance                                                                      |
| `MARKET_PENDING_CURATOR` | `409` | The market has no lender of record yet, so nobody holds `ISSUER_ROLE`. Skipped when confirming with `txHash` |
| `INTERNAL_ERROR`         | `500` | The chain could not be read while confirming. Retry shortly                                                  |

Confirming with `txHash` can also return any [transaction verification error](/endpoints/introduction#confirm-a-transaction).