> For the complete documentation index, see [llms.txt](https://docs.qiro.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qiro.fi/developer-section/qiro-instant-settlement/sdk.md).

# SDK

Install the current package from the release channel supplied during onboarding. Before npm publication, Qiro supplies a versioned tarball and SHA-256 checksum:

```sh
shasum -a 256 -c qiro-rloc-sdk-0.2.0.sha256
pnpm add ./qiro-rloc-sdk-0.2.0.tgz viem
```

Do not install an older `0.1.0` pilot tarball; it predates the facility activation workflow.

```ts
import { createQiroClient } from "@qiro/rloc-sdk";

const qiro = createQiroClient({
  apiBaseUrl: process.env.QIRO_API_BASE_URL!,
  accessToken,
  publicClient
});
```

Use an injected wallet client controlled by the partner. Do not place wallet private keys in application source code or documentation.

## `requestDrawdown`

```ts
const result = await qiro.requestDrawdown({
  facilityId: process.env.QIRO_FACILITY_ID!,
  idempotencyKey: crypto.randomUUID(),
  walletClient,
  client_id: "partner-client-id",
  client_name: "Partner borrower name",
  amount: "500000.00",
  settlement_asset: "USDC",
  use_case: "REMITTANCE_PREFUNDING",
  business_transaction: {
    type: "PAYOUT_BATCH",
    industry_type: "REMITTANCE_AND_MONEY_TRANSFER",
    settle_transaction_id: "partner-transaction-id",
    destination_currency: "PHP",
    destination_country: "PH"
  },
  requested_tenor_days: 3,
  correlation_id: "cor_partner_trace"
});
```

Returns the `drawdownId`, transaction hash, receipt, and verified `DrawdownRequested` event. It does not wait for Qiro admin approval or final funding.

Important failures include `INVALID_INPUT`, `UNAUTHORIZED`, `WALLET_MISMATCH`, `CHAIN_MISMATCH`, `WALLET_SEND_FAILED`, `RECEIPT_WAIT_FAILED`, `REVERTED_RECEIPT`, and `DRAWDOWN_EVENT_MISMATCH`.

## `repayDrawdown`

```ts
const result = await qiro.repayDrawdown({
  drawdownId: "drw_example",
  walletClient,
  readinessTimeoutMs: 30_000,
  pollIntervalMs: 500
});
```

Returns the `repaymentId`, repayment transaction hash, receipt, and final repayment resource after Qiro reports `REPAID`.

Under the hood, the SDK creates the repayment resource, handles bounded token approvals, verifies repayment calldata, sends the financial transaction, checks repayment events in the receipt, and polls the repayment status.

Important failures include `DRAWDOWN_NOT_FUNDED`, `APPROVAL_LOOP_EXCEEDED`, `REPAYMENT_EVENT_MISMATCH`, `REPAYMENT_RECONCILIATION_TIMEOUT`, and `REPAYMENT_QUOTE_EXPIRED`. Errors thrown after repayment creation include the repayment ID, and transaction-related errors include the transaction hash when available.

## `repayAndCloseFacility`

```ts
const result = await qiro.repayAndCloseFacility({
  facilityId: "fac_example",
  walletClient,
  readinessTimeoutMs: 30_000,
  pollIntervalMs: 500
});
```

Returns the `closureId`, repay-and-close transaction hash, receipt, and final closure resource after Qiro reports `CLOSED`.

Under the hood, the SDK creates the closure resource, handles bounded token approvals, verifies `repayDrawdownsAndClose` calldata, sends the financial transaction, checks `RepaymentMade`, expected `DrawdownRepaid` events, and `LOCClosed` in the receipt, and polls closure status.

You do not need to call `repayDrawdown` first for funded active drawdowns. This method repays all known active funded drawdowns plus facility-level dues and closes the LOC in one transaction. It does not run while a drawdown request or repayment is still in-flight.

Important failures include `FACILITY_ALREADY_CLOSED`, `APPROVAL_LOOP_EXCEEDED`, `FACILITY_CLOSURE_EVENT_MISMATCH`, `FACILITY_CLOSURE_RECONCILIATION_TIMEOUT`, and `CLOSURE_QUOTE_EXPIRED`. Errors thrown after closure creation include the closure ID, and transaction-related errors include the transaction hash when available.

## `activateFacility`

```ts
const result = await qiro.activateFacility({
  facilityId: "fac_example",
  walletClient,
  readinessTimeoutMs: 30_000,
  pollIntervalMs: 500
});
```

Returns the `activationId`, activation transaction hash, receipt, and final activation resource after Qiro reports `ACTIVATED`.

The SDK does not require a prior facility read. The activation creation response supplies the trusted chain, LOC, token, fee, and designated wallet. The SDK verifies bounded `approve(loc, 0 | exactFee)` actions and the final `payProcessingFee()` calldata before asking the wallet to sign.

After the wallet broadcasts `payProcessingFee()`, the SDK automatically submits the transaction hash to Qiro and then polls until the activation reaches `ACTIVATED` or `FAILED`. Settle applications should not call `POST /v1/facility-activations/{activation_id}/submission` separately when using `activateFacility()`. If anything becomes uncertain after broadcast, SDK errors include both `activationId` and `transactionHash` when available.

## Read helpers

The current SDK also exposes:

* `getFacility`
* `getDrawdown`
* `getRepayment`
* `getFacilityClosure`
* `getFacilityActivation`
* `getLoc`
* `getDues`
* `listDrawdowns`
* `listRepayments`
* `listActivity`
* `requestDrawdownByLoc`

`requestDrawdownByLoc` is a low-level diagnostic flow. Partner integrations should use facility IDs and `requestDrawdown`.

The current SDK package does not export a high-level `recordRecovery` method.
