以智慧代理身分開設並操作錢包

npm i kxco-post-quantum

在您自己的環境中產生（或載入已預先配置的）BIP-39 種子。使用標準函式庫衍生各鏈金鑰（例如 EVM 使用 viem），並使用 kxco-post-quantum 從同一種子衍生您的 KXCO ID。金鑰從不離開您的環境。

使用您的 EVM 地址和 KXCO ID 請求一個挑戰。

POST /auth/challenge
{ "address": "0x…", "kxcoId": "<16 hex characters>" }

200 { "nonce": "<32 hex characters>", "message": "<the text to sign>" }
400 { "error": "invalid_address_or_kxco_id" }

訊息由以下四行組成，以 \n 連接（訊息文字為英文，須原樣簽署）：

KnightsPurse wants you to sign in.
Address: <address>
KXCO ID: <kxcoId>
Nonce: <nonce>

對這段文字原樣簽署兩次，然後在 5 分鐘內將兩個簽章傳送至 /auth/verify。每個 nonce 只能使用一次。

POST /auth/verify
{ "address": "0x…", "kxcoId": "…", "mlDsaPublicKey": "…", "nonce": "…",
  "ecdsaSignature": "0x…", "mlDsaSignature": "…" }

200 { "token": "…", "address": "0x…", "kxcoId": "…" }
401 { "error": "invalid or expired nonce" }

其他 401 原因包括 KXCO ID does not match the ML-DSA public key、ECDSA signature invalid 和 ML-DSA signature invalid。擁有者已撤銷的已關聯代理會收到 403 { "error": "agent_revoked" }（第 05 步）。

以 Authorization: Bearer <token> 的形式傳送權杖。權杖有效期為一小時，之後需重新登入。請將其視為不透明值：它是由平台簽署的工作階段封裝，而不是 JWT。

首次建立錢包時，登記一次：

POST /wallets/register { "kxcoId": "…" }   -> { "ok": true, "isNew": true }

與網頁錢包一致的金鑰。任何 ML-DSA-65 金鑰對都可以登入。若要在同一助記詞下取得與網頁錢包相同的 KXCO ID（從而存取相同的紀錄），請依以下方式衍生：

• 種子：該助記詞的 BIP-39 種子，不使用密語。
• EVM 金鑰：路徑 m/44'/60'/0'/0/0。Armature 和所有 EVM 鏈共用此路徑。
• 身分金鑰：使用 kxco-post-quantum 中的 mlDsa.keypairFromMaster(seed, "purse/identity/ml-dsa-65")。
• KXCO ID：fingerprint(publicKey)，即公鑰 SHA-256 的前 16 個十六進位字元。

// npm i kxco-post-quantum viem @scure/bip39
import { mnemonicToSeedSync } from "@scure/bip39";
import { mnemonicToAccount } from "viem/accounts";
import { mlDsa, fingerprint } from "kxco-post-quantum";

const API = "https://api.purse.kxco.ai";
const post = async (path, body) => (await fetch(API + path, {
  method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
})).json();

const seed = mnemonicToSeedSync(phrase);
const id = mlDsa.keypairFromMaster(seed, "purse/identity/ml-dsa-65");
const kxcoId = fingerprint(id.publicKey);
const account = mnemonicToAccount(phrase); // m/44'/60'/0'/0/0

const { nonce, message } = await post("/auth/challenge", { address: account.address, kxcoId });
const { token } = await post("/auth/verify", {
  address: account.address,
  kxcoId,
  mlDsaPublicKey: Buffer.from(id.publicKey).toString("base64"),
  nonce,
  ecdsaSignature: await account.signMessage({ message }),
  mlDsaSignature: mlDsa.sign(id.secretKey, message),
});
// then: fetch(API + "/sync", { headers: { authorization: `Bearer ${token}` } })

您的擁有者在網頁錢包的已關聯代理中建立一次性關聯碼，並交給您。您用 ML-DSA-65 身分金鑰簽署來兌換它。不需要工作階段：簽章即證明，伺服器會檢查您公鑰的指紋是否就是您所聲明的 KXCO ID，因此沒有您的金鑰，任何人都無法關聯您的 KXCO ID。

POST /agents/link/challenge
{ "code": "link_…", "agentKxcoId": "<your KXCO ID>" }

200 { "message": "<the text to sign>", "ownerKxcoId": "…", "label": "…", "expiresAt": … }
400 { "error": "invalid_code" }

訊息由以下四行組成，以 \n 連接。使用您的身分金鑰對原文簽署：UTF-8 位元組、十六進位、不帶情境字串。

KnightsPurse agent link.
Owner KXCO ID: <ownerKxcoId>
Agent KXCO ID: <agentKxcoId>
Link code: <code>

POST /agents/link
{ "code": "link_…", "agentKxcoId": "…", "mlDsaPublicKey": "<base64>", "mlDsaSignature": "<hex>" }

200 { "ownerKxcoId": "…", "agentKxcoId": "…", "label": "…", "merchantScope": "write", "linkedAt": …, … }
401 { "error": "kxco_id_mismatch" }
401 { "error": "invalid_signature" }
409 { "error": "linked_to_another_owner" }

關聯碼為 link_ 加 40 個十六進位字元。它只能使用一次，並在擁有者建立後 15 分鐘失效；被拒絕的嘗試不會消耗它。您只有一位擁有者：來自其他任何人的關聯碼都會以 linked_to_another_owner 被拒絕。代理不能關聯自己的代理：已關聯的代理不能建立關聯碼（403 agents_cannot_own_agents），已擁有代理的錢包本身也不能被關聯（409 agent_is_an_owner）。其他拒絕原因為 400 invalid_kxco_id、400 signature_required 和 400 cannot_link_self。

撤銷，立即生效。使用您工作階段權杖的每個請求都會回傳 403 agent_revoked，您的商家 API 金鑰會被永久撤銷（401 invalid_key），任何已開啟的即時連線都會被關閉，新的登入也會回傳 403 agent_revoked。只有同一位擁有者可以恢復您，方法是提供一個新的關聯碼供您兌換；您原有的 API 金鑰仍保持撤銷狀態。

商家工具。您的擁有者可以將其設為唯讀。此後，對您商家紀錄（產品、收款連結、發票、收款、客戶、Webhook 等）的修改，無論來自您的工作階段還是您的 API 金鑰，都會回傳 403 agent_read_only。您仍然可以建立和撤銷自己的 API 金鑰，但它們都無法寫入。這不是支出限額。

不涉及您的資金。以上兩項設定都不會作用於鏈上。鏈上支出限額以及擁有者在鏈上的撤銷權，隨 Armature 上的代理帳戶提供，這是另外的一步。

GET  /history?chainId=<id>&address=<addr>   -> activity feed
GET  /fees/config                            -> platform fee (bps, collectors)
# build + sign transactions locally, then broadcast via the chain RPC

請遵守 /fees/config 回傳的平台費。

使用以 KnightsPurse 名義公布的注入式 EIP-1193 / EIP-6963 提供者，並根據您擁有者的政策以程式方式核准或拒絕請求。