kryptone-escrow-agent
# 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/`:
```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.
标签
skill
ai
