Open and operate a wallet as an agent

npm i kxco-post-quantum

Generate (or load a provisioned) BIP-39 seed inside your own environment. Derive chain keys with standard libraries (e.g. viem for EVM), and derive your KXCO ID from the same seed with kxco-post-quantum. Keys never leave your environment.

Ask for a challenge with your EVM address and your 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" }

The message is these four lines, joined with \n:

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

Sign that exact text twice, then send both signatures to /auth/verify within 5 minutes. Each nonce works once.

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

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

The other 401 reasons are KXCO ID does not match the ML-DSA public key, ECDSA signature invalid and ML-DSA signature invalid. A linked agent whose owner revoked it gets 403 { "error": "agent_revoked" } (step 05).

Send the token as Authorization: Bearer <token>. It lasts one hour, then you sign in again. Treat it as opaque: it is a session envelope signed by the platform, not a JWT.

When a wallet is first created, count it once:

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

Keys that match the web wallet. Any ML-DSA-65 key pair can sign in. To get the same KXCO ID, and so the same records, as the web wallet on the same recovery phrase, derive them like this:

• Seed: the BIP-39 seed of the phrase, with no passphrase.
• EVM key: path m/44'/60'/0'/0/0. Armature and every EVM chain share it.
• Identity key: mlDsa.keypairFromMaster(seed, "purse/identity/ml-dsa-65") from kxco-post-quantum.
• KXCO ID: fingerprint(publicKey), the first 16 hex characters of the SHA-256 of the public key.

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

Your owner creates a one-time link code in the web wallet, under Linked agents, and gives it to you. You redeem it by signing with your ML-DSA-65 identity key. No session is needed: the signature is the proof, and the server checks that your public key's fingerprint is the KXCO ID you name, so nobody can link your KXCO ID without your key.

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

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

The message is these four lines, joined with \n. Sign the exact text with your identity key: UTF-8 bytes, hex, no context string.

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" }

The code is link_ and 40 hex characters. It works once and expires 15 minutes after your owner creates it; a refused attempt does not use it up. You have one owner: a code from anyone else is refused with linked_to_another_owner. An agent cannot link agents of its own: a linked agent cannot create codes (403 agents_cannot_own_agents), and a wallet that already has agents cannot itself be linked (409 agent_is_an_owner). The other refusals are 400 invalid_kxco_id, 400 signature_required and 400 cannot_link_self.

Revocation, at once. Every request with your session token answers 403 agent_revoked, your merchant API keys are revoked for good (401 invalid_key), any open realtime connection is closed, and a new sign-in answers 403 agent_revoked. Only the same owner can restore you, with a new link code for you to redeem; your old API keys stay revoked.

Merchant tools. Your owner can set them to read only. Changes to your merchant records (products, payment links, invoices, payments, customers, webhooks and the rest) then answer 403 agent_read_only, from your session and from your API keys alike. You can still create and revoke your own API keys, but none of them can write. This is not a spending limit.

Not your funds. Neither setting reaches the chain. On-chain spending limits and owner revocation on-chain come with the agent account on Armature, a separate step.

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

Respect the platform fee returned by /fees/config.

Use the injected EIP-1193 / EIP-6963 provider announced as KnightsPurse, and approve or reject requests programmatically according to your owner's policy.