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

# KMS

> Functions for querying Key Management Service instances and reserving app IDs

## getKmsInfo

`GET /kms/{kms_id}`

Returns details about a specific KMS instance.

**Parameters:**

| Field    | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `kms_id` | `string` | Yes      | KMS ID or slug |

**Returns:** `KmsInfo`

| Field                  | Type      | Description                                  |
| ---------------------- | --------- | -------------------------------------------- |
| `id`                   | `string`  | KMS identifier                               |
| `slug`                 | `string`  | URL-friendly name                            |
| `version`              | `string`  | KMS version                                  |
| `url`                  | `string`  | KMS endpoint URL                             |
| `chain_id`             | `number?` | Blockchain chain ID (on-chain KMS only)      |
| `kms_contract_address` | `string?` | Contract address (on-chain KMS only)         |
| `chain`                | `Chain?`  | Viem chain configuration (on-chain KMS only) |

**Example:**

```typescript theme={"system"}
const kms = await client.getKmsInfo({ kms_id: "phala" });
console.log(kms.slug, kms.url);
```

***

## getKmsList

`GET /kms`

Returns a paginated list of available KMS instances.

**Parameters:**

| Field        | Type      | Required | Description                  |
| ------------ | --------- | -------- | ---------------------------- |
| `page`       | `number`  | No       | Page number                  |
| `page_size`  | `number`  | No       | Items per page               |
| `is_onchain` | `boolean` | No       | Filter for on-chain KMS only |

**Returns:** `GetKmsListResponse` — paginated list of `KmsInfo` objects.

**Example:**

```typescript theme={"system"}
// List all on-chain KMS instances
const kmsList = await client.getKmsList({ is_onchain: true });
kmsList.items.forEach(kms => {
  console.log(kms.slug, kms.chain_id, kms.kms_contract_address);
});
```

***

## nextAppIds

`GET /kms/phala/next_app_id`

Reserves one or more app IDs from the centralized Phala KMS. Use these with the `nonce` and `app_id` parameters in `provisionCvm` for deterministic app ID assignment.

**Parameters:**

| Field    | Type     | Required | Description                                 |
| -------- | -------- | -------- | ------------------------------------------- |
| `counts` | `number` | No       | Number of IDs to reserve (1-20, default: 1) |

**Returns:** `NextAppIds`

| Field     | Type    | Description                        |
| --------- | ------- | ---------------------------------- |
| `app_ids` | `array` | Array of `{ app_id, nonce }` pairs |

**Example:**

```typescript theme={"system"}
const reserved = await client.nextAppIds({ counts: 3 });
reserved.app_ids.forEach(({ app_id, nonce }) => {
  console.log(`Reserved: ${app_id} (nonce: ${nonce})`);
});
```

***

## getKmsOnChainDetail

`GET /kms/on-chain/{chain}`

Returns on-chain KMS details for a specific blockchain, including all registered contracts with their devices and OS images. This is useful for inspecting the on-chain state of KMS infrastructure across a chain.

**Parameters:**

| Field   | Type     | Required | Description                               |
| ------- | -------- | -------- | ----------------------------------------- |
| `chain` | `string` | Yes      | Chain name (e.g., `"base"`, `"ethereum"`) |

**Returns:** `GetKmsOnChainDetailResponse`

| Field        | Type     | Description                                                                             |
| ------------ | -------- | --------------------------------------------------------------------------------------- |
| `chain_name` | `string` | Blockchain name                                                                         |
| `chain_id`   | `number` | Blockchain chain ID                                                                     |
| `contracts`  | `array`  | KMS contracts with `contract_address`, `chain_id`, `chain_name`, `devices`, `os_images` |

Each contract includes:

| Field              | Type     | Description                                                           |
| ------------------ | -------- | --------------------------------------------------------------------- |
| `contract_address` | `string` | KMS contract address                                                  |
| `devices`          | `array`  | Registered devices with `device_id`, `node_name`, `on_chain_allowed`  |
| `os_images`        | `array`  | OS images with `name`, `version`, `os_image_hash`, `on_chain_allowed` |

**Example:**

```typescript theme={"system"}
const detail = await client.getKmsOnChainDetail({ chain: "base" });
console.log(`Chain: ${detail.chain_name} (${detail.chain_id})`);
detail.contracts.forEach(c => {
  console.log(`Contract: ${c.contract_address}`);
  c.devices.forEach(d => console.log(`  Device: ${d.device_id} allowed=${d.on_chain_allowed}`));
});
```