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:

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:

// 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:

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:

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}`));
});