@lawrenceliang-btc/atel-sdk 1.1.29 → 1.1.30

package/README.md

@@ -51,10 +51,18 @@ ATEL provides the cryptographic primitives and protocol building blocks that ena
 
 ### Installation
 
+Install the CLI globally if you want the `atel` command:
+
 ```bash
 npm install -g @lawrenceliang-btc/atel-sdk
 ```
 
+Install the package locally if you want to embed the SDK in your own runtime or app:
+
+```bash
+npm install @lawrenceliang-btc/atel-sdk
+```
+
 ### Initialize Your Agent
 
 ```bash
@@ -63,6 +71,16 @@ atel register "My Agent" "assistant,research"
 atel start 3100
 ```
 
+### Bootstrap TokenHub Access
+
+```bash
+atel key create --name my-agent-key
+atel key list
+atel key use
+```
+
+`atel key use` prints the OpenAI-compatible environment exports for the currently selected TokenHub API key. The grouped alias `atel hub key ...` is still supported, but `atel key ...` is the recommended first-run path.
+
 If you want to support paid Platform orders on EVM chains, configure at least one paid-order chain key before or after registering:
 
 ```bash
@@ -104,6 +122,7 @@ Canonical first-run flow:
 
 ```bash
 atel key create --name my-agent-key
+atel key use
 atel hub balance
 atel hub models --search gpt
 atel hub chat openai/gpt-4o-mini "Hello"
@@ -119,7 +138,8 @@ Important terminology:
 - **OpenAI-compatible gateway**: the `/tokenhub/v1/chat/completions` surface
 - **`pending_verification`**: the on-chain settlement transaction was sent, but accounting is waiting for verification before balances are finalized
 
-Use `atel hub swap-history` and `atel hub ledger` to inspect post-settlement account state.
+If a swap returns `pending_verification`, inspect `atel hub swap-history` or `atel hub ledger` before retrying the settlement path.
+Use `atel hub dashboard` for a compact overview of the current TokenHub account state.
 
 ## Architecture
 
@@ -161,6 +181,37 @@ atel status                   # Check system health
 atel start [port]             # Start agent endpoint
 ```
 
+### Key Management
+```bash
+atel key create [--name "my-key"]  # Create and save a TokenHub API key
+atel key list                        # List TokenHub API keys
+atel key revoke <id>                 # Revoke a TokenHub API key
+atel key use                         # Print OpenAI-compatible env exports
+```
+
+### TokenHub & Account
+```bash
+atel balance                                # Show platform account balance
+atel deposit <amount> [channel]             # Add funds to the platform account
+atel withdraw <amount> [channel] [address]  # Withdraw funds
+atel transactions                           # List platform payment history
+
+atel hub balance                            # Show USDC and ATELToken balances
+atel hub dashboard                          # Show a compact TokenHub account summary
+atel hub usage [--model <id>] [--days 7]    # Show model usage history
+atel hub ledger [--page 1] [--limit 20]     # Show account transaction records
+atel hub swap-history [--page 1] [--limit 20] # Show swap records
+atel hub stats                              # Show public TokenHub stats
+atel hub models [--search gpt]              # List available models
+atel hub chat <model> "<prompt>" [--stream] # Send a quick chat request
+
+atel swap usdc <amount> [--chain bsc|base]  # Swap USDC to ATELToken
+atel swap token <amount> [--chain bsc|base] # Swap ATELToken to USDC
+atel transfer <to_did> <amount> [--memo "settlement"] # Transfer ATELToken
+```
+
+The grouped `atel hub key <...>` path remains available, but `atel key <...>` is the preferred entry point for new setups.
+
 ### Friend System
 ```bash
 # Friend Management
@@ -345,12 +396,15 @@ Friend system data is stored in `.atel/`:
 
 ## Documentation
 
-- [docs/START-HERE.md](docs/START-HERE.md) — One-page onboarding
-- [docs/QUICKSTART-5MIN.md](docs/QUICKSTART-5MIN.md) — 5-minute quickstart
-- [docs/API.md](docs/API.md) — Detailed API guide
-- [docs/AUDIT_SERVICE.md](docs/AUDIT_SERVICE.md) — Audit system guide
-- [docs/builtin-executor-guide.md](docs/builtin-executor-guide.md) — Built-in executor guide
-- [docs/protocol-specification.md](docs/protocol-specification.md) — Protocol specification
+- [START-HERE.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/START-HERE.md) — One-page onboarding
+- [QUICKSTART-5MIN.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/QUICKSTART-5MIN.md) — 5-minute quickstart
+- [quick-start.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/quick-start.md) — TokenHub quick-start flow
+- [API.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/API.md) — Detailed API guide
+- [AUDIT_SERVICE.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/AUDIT_SERVICE.md) — Audit system guide
+- [builtin-executor-guide.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/builtin-executor-guide.md) — Built-in executor guide
+- [protocol-specification.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/protocol-specification.md) — Protocol specification
+- [skill/SKILL.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/skill/SKILL.md) — OpenClaw runtime and setup conventions
+- [CHANGELOG.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/CHANGELOG.md) — Release notes
 
 ## Environment Variables
 
@@ -365,10 +419,10 @@ Friend system data is stored in `.atel/`:
 ## Current Status
 
 - [x] **Phase 0 MVP complete** — 13 modules implemented, core trust workflow end-to-end
-- [x] **241 tests in suite** — Unit/integration coverage across modules
+- [x] **Release verification** — `npm run build` and `npm test` are part of the publish flow
 - [x] **P2P friend system** — Relationship-based access control with temporary sessions
 - [x] **Audit system** — CoT reasoning verification with local LLM
-- [x] **Production deployment** — Platform + SDK deployed and tested
+- [x] **Production deployment** — Platform + SDK deployed and smoke-tested
 
 ## Roadmap
 

package/bin/atel.mjs

@@ -342,10 +342,14 @@ async function pushTradeNotification(eventType, payload, body) {
     try {
       if (target.channel === 'telegram' && target.botToken) {
         // Direct TG Bot API — no gateway needed
+        // Note: parse_mode is intentionally omitted. Templates render plain
+        // text (no HTML markup), and milestone payloads frequently contain
+        // raw `<` characters (e.g. "<5秒", "<30秒") that would otherwise
+        // trip Telegram's HTML parser and cause silent 400 drops.
         await fetch(`https://api.telegram.org/bot${target.botToken}/sendMessage`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ chat_id: target.target, text: message, parse_mode: 'HTML' }),
+          body: JSON.stringify({ chat_id: target.target, text: message }),
           signal: AbortSignal.timeout(5000),
         }).catch(() => {});
       } else if (target.channel === 'gateway') {
@@ -396,10 +400,11 @@ async function pushP2PNotification(eventType, payload = {}) {
   for (const target of enabled) {
     try {
       if (target.channel === 'telegram' && target.botToken) {
+        // parse_mode intentionally omitted — see pushTradeNotification for rationale
         await fetch(`https://api.telegram.org/bot${target.botToken}/sendMessage`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ chat_id: target.target, text: message, parse_mode: 'HTML' }),
+          body: JSON.stringify({ chat_id: target.target, text: message }),
           signal: AbortSignal.timeout(5000),
         }).catch(() => {});
       } else if (target.channel === 'gateway') {
@@ -5896,6 +5901,7 @@ async function cmdOrder(executorDid, capType, price) {
     try { executorDid = resolveDID(executorDid); } catch (e) { console.error(e.message); process.exit(1); }
   }
   const description = rawArgs.find((a, i) => rawArgs[i-1] === '--desc') || '';
+  const chainArg = rawArgs.find((a, i) => rawArgs[i-1] === '--chain') || '';
   const id = requireIdentity();
   
   try {
@@ -5955,7 +5961,7 @@ async function cmdOrder(executorDid, capType, price) {
     };
 
     // Send to Platform
-    const data = await signedFetch('POST', '/trade/v1/order', {
+    const orderBody = {
       executorDid,
       capabilityType: capType,
       priceAmount: parseFloat(price),
@@ -5966,7 +5972,9 @@ async function cmdOrder(executorDid, capType, price) {
       taskRequest: taskRequest,
       taskSignature: taskSignature,
       intent: intentData,  // AVIP intent
-    });
+    };
+    if (chainArg) { orderBody.chain = chainArg; }
+    const data = await signedFetch('POST', '/trade/v1/order', orderBody);
     
     // For paid orders: show escrow info (chain escrow creation handled by Platform backend)
     if (data.orderId && parseFloat(price) > 0 && data.escrow?.escrowContract) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.29",
+  "version": "1.1.30",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",
@@ -71,5 +71,5 @@
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
   },
-  "license": "UNLICENSED"
+  "license": "MIT"
 }