# API Reference

### Type Definitions

#### Basic Types

| Type            | Description                                   |
| --------------- | --------------------------------------------- |
| `BoostId`       | `nat` - Unique identifier for boost requests  |
| `BoosterPoolId` | `nat` - Unique identifier for booster pools   |
| `Subaccount`    | `blob` - ICRC-1 subaccount for fund isolation |
| `Amount`        | `nat` - Amount in satoshis                    |
| `Timestamp`     | `int` - Unix timestamp in nanoseconds         |
| `Fee`           | `float64` - Fee percentage (0.1 to 10.0)      |

#### Status Types

```candid
type BoostStatus = variant {
  pending;     // Waiting for booster acceptance
  active;      // Booster matched, waiting for Bitcoin
  completed;   // Transaction completed successfully
  cancelled;   // Request cancelled
  boosted;     // ckBTC provided, waiting for reclamation
  minting;     // Minting process in progress
};
```

#### Record Types

```candid
type BoostRequest = record {
  id: BoostId;
  owner: principal;
  amount: Amount;
  fee: Fee;
  receivedBTC: Amount;
  btcAddress: opt text;
  subaccount: Subaccount;
  status: BoostStatus;
  matchedBoosterPool: opt BoosterPoolId;
  createdAt: Timestamp;
  updatedAt: Timestamp;
};

type BoosterPool = record {
  id: BoosterPoolId;
  owner: principal;
  fee: Fee;
  subaccount: Subaccount;
  availableAmount: Amount;
  totalBoosted: Amount;
  createdAt: Timestamp;
  updatedAt: Timestamp;
};
```

#### Result Types

```candid
type BoostRequestResult = variant { ok: BoostRequest; err: text };
type BoosterPoolResult = variant { ok: BoosterPool; err: text };
type TextResult = variant { ok: text; err: text };
```

### Helper Functions

Utility functions for conversions and system information.

| Function               | Parameters | Returns        | Description                       |
| ---------------------- | ---------- | -------------- | --------------------------------- |
| `ckBTCToSatoshis`      | `float64`  | `nat`          | Converts ckBTC amount to satoshis |
| `satoshisToCkBTC`      | `nat`      | `float64`      | Converts satoshis to ckBTC amount |
| `getCanisterPrincipal` | none       | `text` (query) | Gets the canister's principal ID  |
| `getDirectBTCAddress`  | none       | `text`         | Gets the main Bitcoin address     |

#### System Functions

| Function | Parameters | Returns        | Description                |
| -------- | ---------- | -------------- | -------------------------- |
| `greet`  | `text`     | `text` (query) | Basic greeting function    |
| `whoami` | none       | `text`         | Returns caller's principal |

### Boost Request Operations

Functions for creating, managing, and querying boost requests.

#### Request Lifecycle

| Function                    | Parameters          | Returns              | Purpose                           |
| --------------------------- | ------------------- | -------------------- | --------------------------------- |
| `registerBoostRequest`      | `Amount`, `Fee`     | `BoostRequestResult` | Create new boost request          |
| `updateReceivedBTC`         | `BoostId`, `Amount` | `BoostRequestResult` | Update Bitcoin deposit amount     |
| `getBoostRequestBTCAddress` | `BoostId`           | `TextResult`         | Get Bitcoin address for request   |
| `checkBTCDeposit`           | `BoostId`           | `BoostRequestResult` | Check and update Bitcoin deposits |

#### Request Queries

| Function               | Parameters  | Returns                    | Purpose                    |
| ---------------------- | ----------- | -------------------------- | -------------------------- |
| `getBoostRequest`      | `BoostId`   | `opt BoostRequest` (query) | Get specific request by ID |
| `getUserBoostRequests` | `principal` | `vec BoostRequest` (query) | Get all requests for user  |
| `getAllBoostRequests`  | none        | `vec BoostRequest` (query) | Get all requests in system |

#### Function Details

**`registerBoostRequest(Amount, Fee) -> BoostRequestResult`**

Creates a new boost request for instant ckBTC conversion.

* **Amount**: Satoshis to convert (minimum: 10,000)
* **Fee**: Maximum fee percentage (0.1 - 10.0)
* **Errors**: Invalid amount, invalid fee, address generation failure

**`updateReceivedBTC(BoostId, Amount) -> BoostRequestResult`**

Updates the Bitcoin amount received for a request.

* **BoostId**: Target request identifier
* **Amount**: Bitcoin amount received in satoshis
* **Errors**: Request not found, invalid status, invalid amount

**`getBoostRequestBTCAddress(BoostId) -> TextResult`**

Retrieves the unique Bitcoin address for a boost request.

* **BoostId**: Target request identifier
* **Returns**: Bitcoin address string
* **Errors**: Request not found, address not generated

**`checkBTCDeposit(BoostId) -> BoostRequestResult`**

Monitors and updates Bitcoin deposits for a request.

* **BoostId**: Target request identifier
* **Returns**: Updated request with current Bitcoin balance
* **Errors**: Request not found, monitoring failure

### Booster Pool Operations

Functions for liquidity providers to manage their capital pools.

#### Pool Management

| Function              | Parameters | Returns             | Purpose                 |
| --------------------- | ---------- | ------------------- | ----------------------- |
| `registerBoosterPool` | `Fee`      | `BoosterPoolResult` | Create new booster pool |

#### Pool Queries

| Function              | Parameters      | Returns                   | Purpose                 |
| --------------------- | --------------- | ------------------------- | ----------------------- |
| `getBoosterPool`      | `BoosterPoolId` | `opt BoosterPool` (query) | Get specific pool by ID |
| `getUserBoosterPools` | `principal`     | `vec BoosterPool` (query) | Get all pools for user  |
| `getAllBoosterPools`  | none            | `vec BoosterPool` (query) | Get all pools in system |

#### Function Details

**`registerBoosterPool(Fee) -> BoosterPoolResult`**

Creates a new liquidity pool for providing instant ckBTC.

* **Fee**: Fee percentage charged (0.1 - 10.0)
* **Errors**: User already has pool, invalid fee percentage

### Advanced Operations

Core protocol operations for boosters and users.

#### Booster Operations

| Function                        | Parameters            | Returns                | Purpose                        |
| ------------------------------- | --------------------- | ---------------------- | ------------------------------ |
| `acceptBoostRequest`            | `BoostId`             | `text`                 | Accept a pending boost request |
| `registerBoosterAccount`        | `Fee`                 | `BoosterAccountResult` | Create booster account         |
| `updateBoosterDeposit`          | `principal`, `Amount` | `BoosterAccountResult` | Add liquidity to account       |
| `withdrawBoosterFunds`          | `Amount`              | `text`                 | Remove liquidity from account  |
| `triggerMintingForBoostReclaim` | `BoostId`             | `text`                 | Start fund reclamation process |
| `reclaimMintedFunds`            | `BoostId`             | `text`                 | Complete fund reclamation      |

#### User Fallback Operations

<table><thead><tr><th width="308.6484375">Function</th><th>Parameters</th><th width="91.45703125">Returns</th><th>Purpose</th></tr></thead><tbody><tr><td><code>triggerMintingForMyBoostRequest</code></td><td><code>BoostId</code></td><td><code>text</code></td><td>Start direct minting (no booster)</td></tr><tr><td><code>claimMintedCKBTC</code></td><td><code>BoostId</code></td><td><code>text</code></td><td>Complete direct minting</td></tr></tbody></table>

#### Additional Query Functions

<table><thead><tr><th width="184.14453125">Function</th><th>Parameters</th><th>Returns</th><th>Purpose</th></tr></thead><tbody><tr><td><code>getBoosterAccount</code></td><td><code>principal</code></td><td><code>opt BoosterAccount</code> (query)</td><td>Get booster account by principal</td></tr><tr><td><code>getAllBoosterAccounts</code></td><td>none</td><td><code>vec BoosterAccount</code> (query)</td><td>Get all booster accounts</td></tr><tr><td><code>getPendingBoostRequests</code></td><td>none</td><td><code>vec BoostRequest</code> (query)</td><td>Get all pending requests</td></tr><tr><td><code>getBoostedRequests</code></td><td>none</td><td><code>vec BoostRequest</code> (query)</td><td>Get all boosted requests</td></tr><tr><td><code>getMintingRequests</code></td><td>none</td><td><code>vec BoostRequest</code> (query)</td><td>Get all minting requests</td></tr></tbody></table>