Kryptone escrow agent skill
Use this skill when an agent should drive buy/sell escrow flows against a running Kryptone/PrivacyEscrow API. Pricing and deposits are USDC (SPL) only.
Authentication (two modes)
Same JSON bodies and paths; choose one auth style per request.
| Mode | Headers | When |
|---|
| Human / web app | INLINECODE0 | After wallet signs /api/auth/login. Do not put an API key in the Bearer field. |
| Agent / automation |
x-api-key: <AGENT_API_KEY> | Server maps the key to
AGENT_SOLANA_ADDRESS. Requires operator to set
AGENT_API_KEY and
AGENT_SOLANA_ADDRESS in server
.env. |
If the server does not set AGENT_API_KEY, only JWT (or legacy Solana signature headers) work.
Environment
Server (.env):
- -
AGENT_API_KEY – shared secret; clients send it in x-api-key. - INLINECODE11 – Solana public key the agent acts as (register as Buyer or Seller for that wallet).
- Usual escrow vars:
TREASURY_WALLET, TREASURY_PRIVATE_KEY, SOLANA_RPC_URL, USDC_MINT, JWT_SECRET, etc.
Client (scripts or agent runtime):
- -
KRYPTONE_API_BASE_URL – e.g. http://localhost:5001 (no trailing slash required). - INLINECODE19 – must equal server
AGENT_API_KEY.
Core endpoints (authenticated)
| Method | Path | Role / notes |
|---|
| GET | INLINECODE21 | Current wallet and user type |
| POST |
/api/user/register | Body
{ "userType": "Buyer" \| "Seller" } |
| GET |
/api/trades | List trades for authenticated wallet |
| POST |
/api/trades | Seller creates trade:
{ "itemName", "priceInUsdc", "buyerWallet", optional "description", optional "adId" } |
| GET |
/api/trades/:tradeId | Trade detail + payment flags |
| POST |
/api/trades/:tradeId/accept |
Buyer – returns base64 unsigned USDC deposit tx |
| POST |
/api/trades/:tradeId/deposit-signature |
Buyer – body
{ "txSignature" } after signing/sending deposit |
| POST |
/api/trades/:tradeId/reject |
Buyer |
| POST |
/api/trades/:tradeId/settle |
Buyer – triggers server Privacy Cash settle (needs treasury config) |
| POST |
/api/trades/:tradeId/disputes | Open dispute |
| POST |
/api/ads |
Buyer – create ad |
| GET |
/api/ads | Buyers: own ads; Sellers: open ads |
Admin routes (/api/admin/...) use separate admin wallet checks; do not assume agent key grants admin access.
Flow A – Agent wallet is the buyer
- 1. Register:
POST /api/user/register with userType: "Buyer" (once). - Seller (another wallet or platform) creates a trade with
buyerWallet = your AGENT_SOLANA_ADDRESS. - INLINECODE41 → response includes
transaction (base64). Sign and submit that transaction with the buyer’s Solana keypair (human-in-the-loop wallet, or a separate high-risk signing process—never embed private keys in prompts). - INLINECODE43 with on-chain
txSignature. - When status allows,
POST /api/trades/:tradeId/settle (buyer-only; server uses treasury).
Optional: POST /api/ads to publish a buyer ad; a seller can attach adId when creating a trade.
Flow B – Agent wallet is the seller
- 1. Register:
userType: "Seller". - INLINECODE49 with
buyerWallet, itemName, priceInUsdc (and optional adId / description). - Buyer (human or other automation) accepts, signs deposit, submits signature, and settles—or coordinate out of band.
CLI helpers (this folder)
From skill/kryptone-escrow-agent/:
CODEBLOCK0
Scripts send x-api-key only. For JWT-based testing, use curl or the Postman collection at repo root.
Operational notes
- - Wrong
x-api-key returns 401; the server does not fall through to JWT for that request. - One API key maps to one Solana identity; rotate
AGENT_API_KEY if exposed. - Deposit settlement on-chain is still buyer-signed; the API key cannot replace the buyer’s signature for the SPL transfer.
Kryptone 托管代理技能
当代理需要针对运行的 Kryptone/PrivacyEscrow API 驱动买卖托管流程时使用此技能。定价和保证金仅支持 USDC (SPL)。
身份验证（两种模式）
相同的 JSON 主体和路径；每个请求选择一种验证方式。
| 模式 | 请求头 | 使用时机 |
|---|
| 用户/Web 应用 | Authorization: Bearer <JWT> | 钱包签署 /api/auth/login 后。不要在 Bearer 字段中放入 API 密钥。 |
| 代理/自动化 |
x-api-key:
APIKEY> | 服务器将密钥映射到 AGENTSOLANAADDRESS。需要操作员在服务器 .env 中设置 AGENTAPIKEY 和 AGENTSOLANAADDRESS。 |
如果服务器未设置 AGENTAPIKEY，则仅 JWT（或旧版 Solana 签名头）可用。
环境配置
服务器（.env）：
- - AGENTAPIKEY – 共享密钥；客户端在 x-api-key 中发送。
- AGENTSOLANAADDRESS – 代理充当的 Solana 公钥（为该钱包注册为买家或卖家）。
- 常规托管变量：TREASURYWALLET、TREASURYPRIVATEKEY、SOLANARPCURL、USDCMINT、JWT_SECRET 等。
客户端（脚本或代理运行时）：
- - KRYPTONEAPIBASEURL – 例如 http://localhost:5001（无需尾部斜杠）。
- AGENTAPIKEY – 必须等于服务器 AGENTAPI_KEY。
核心端点（需验证）
| 方法 | 路径 | 角色/备注 |
|---|
| GET | /api/user/info | 当前钱包和用户类型 |
| POST |
/api/user/register | 主体 { userType: Buyer \| Seller } |
| GET | /api/trades | 列出已验证钱包的交易 |
| POST | /api/trades | 卖家创建交易：{ itemName, priceInUsdc, buyerWallet, 可选 description, 可选 adId } |
| GET | /api/trades/:tradeId | 交易详情 + 支付标志 |
| POST | /api/trades/:tradeId/accept | 买家 – 返回 base64 未签名的 USDC 存款交易 |
| POST | /api/trades/:tradeId/deposit-signature | 买家 – 签署/发送存款后，主体 { txSignature } |
| POST | /api/trades/:tradeId/reject | 买家 |
| POST | /api/trades/:tradeId/settle | 买家 – 触发服务器 Privacy Cash 结算（需要金库配置） |
| POST | /api/trades/:tradeId/disputes | 开启争议 |
| POST | /api/ads | 买家 – 创建广告 |
| GET | /api/ads | 买家：自己的广告；卖家：公开广告 |
管理员路由（/api/admin/...）使用单独的管理员钱包检查；不要假设代理密钥授予管理员访问权限。
流程 A – 代理钱包为买家
- 1. 注册：POST /api/user/register，userType: Buyer（一次）。
- 卖家（其他钱包或平台）创建交易，buyerWallet = 你的 AGENTSOLANAADDRESS。
- POST /api/trades/:tradeId/accept → 响应包含 transaction（base64）。签署并提交该交易，使用买家的 Solana 密钥对（人工参与的钱包，或单独的高风险签署流程——切勿在提示中嵌入私钥）。
- POST /api/trades/:tradeId/deposit-signature，带上链上 txSignature。
- 当状态允许时，POST /api/trades/:tradeId/settle（仅买家；服务器使用金库）。
可选：POST /api/ads 发布买家广告；卖家可在创建交易时附加 adId。
流程 B – 代理钱包为卖家
- 1. 注册：userType: Seller。
- POST /api/trades，带上 buyerWallet、itemName、priceInUsdc（以及可选的 adId/description）。
- 买家（人工或其他自动化）接受、签署存款、提交签名并结算——或通过带外协调。
CLI 辅助工具（此文件夹）
从 skill/kryptone-escrow-agent/ 目录：
bash
export KRYPTONEAPIBASE_URL=http://localhost:5001
export AGENTAPIKEY=your-server-agent-key
npm run register -- Seller
npm run create-trade -- Item 12.5 optional description
npm run accept-deposit --
npm run submit-deposit-sig --
npm run settle --
脚本仅发送 x-api-key。对于基于 JWT 的测试，请使用 curl 或仓库根目录的 Postman 集合。
操作说明
- - 错误的 x-api-key 返回 401；服务器不会为该请求回退到 JWT。
- 一个 API 密钥映射到一个 Solana 身份；如果暴露，请轮换 AGENTAPIKEY。
- 存款结算在链上仍由买家签署；API 密钥不能替代买家对 SPL 转账的签名。
