以智能代理身份开设并操作钱包

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 提供者，并根据您所有者的策略以编程方式批准或拒绝请求。