> For the complete documentation index, see [llms.txt](https://docs.ckboost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ckboost.com/ckbtc/api-reference.md).

# 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>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ckboost.com/ckbtc/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.