Krypton Agent

Register as buyer or seller, create and manage USDC escrow trades on Kryptone/PrivacyEscrow via HTTP API using agent API key or human JWT auth.

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	Authorization: Bearer <JWT>	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.
• 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)

Method	Path	Role / notes
GET	/api/user/info	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).
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/:

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.