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.

ModeHeadersWhenHuman / web appAuthorization: Bearer <JWT>After wallet signs /api/auth/login. Do not put an API key in the Bearer field.Agent / automationx-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.
• AGENT_SOLANA_ADDRESS – 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).
• AGENT_API_KEY – must equal server AGENT_API_KEY.

Core endpoints (authenticated)#

MethodPathRole / notesGET/api/user/infoCurrent wallet and user typePOST/api/user/registerBody { "userType": "Buyer" | "Seller" }GET/api/tradesList trades for authenticated walletPOST/api/tradesSeller creates trade: { "itemName", "priceInUsdc", "buyerWallet", optional "description", optional "adId" }GET/api/trades/:tradeIdTrade detail + payment flagsPOST/api/trades/:tradeId/acceptBuyer – returns base64 unsigned USDC deposit txPOST/api/trades/:tradeId/deposit-signatureBuyer – body { "txSignature" } after signing/sending depositPOST/api/trades/:tradeId/rejectBuyerPOST/api/trades/:tradeId/settleBuyer – triggers server Privacy Cash settle (needs treasury config)POST/api/trades/:tradeId/disputesOpen disputePOST/api/adsBuyer – create adGET/api/adsBuyers: 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).
2. Seller (another wallet or platform) creates a trade with buyerWallet = your AGENT_SOLANA_ADDRESS.
3. POST /api/trades/:tradeId/accept → 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).
4. POST /api/trades/:tradeId/deposit-signature with on-chain txSignature.
5. 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".
2. POST /api/trades with buyerWallet, itemName, priceInUsdc (and optional adId / description).
3. 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/:

bash

export KRYPTONE_API_BASE_URL=http://localhost:5001
export AGENT_API_KEY=your-server-agent-key

npm run register -- Seller
npm run create-trade -- <buyerWallet> "Item" 12.5 "optional description"
npm run accept-deposit -- <tradeId>
npm run submit-deposit-sig -- <tradeId> <onChainSignature>
npm run settle -- <tradeId>

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.