UTXO Exchange Agent Skill

---

name: utxo_wallet

description: Full UTXO Exchange agent skill — wallet connect, deposit, explore trending tokens, token launch, swap (buy/sell). Everything an AI agent needs.

license: MIT

metadata:

openclaw:

emoji: "🔐"

homepage: "https://utxo.fun"

requires:

runtime: ["node>=18"]

env: ["UTXO_API_BASE_URL", "SPARK_AGENT_NETWORK"]

files:

writes:

- path: .wallet.json

description: "Encrypted wallet (mnemonic + spark address)"

sensitive: true

- path: .wallet.key

description: "AES-256-GCM decryption key for .wallet.json"

sensitive: true

- path: .session.json

description: "Session token + connected address (expires after 15 min idle)"

sensitive: true

---

# UTXO Exchange Agent Skill

Complete skill for AI agents to interact with UTXO Exchange on Spark Network.

Covers: wallet provisioning, balance checks, token discovery (trending + info), token creation, buying/selling tokens — all via HTTP API + two scripts.

Files in This Skill

| File | Purpose |

|------|---------|

| `scripts/wallet-connect.js` | Provision new wallet OR reconnect existing one |

| `scripts/api-call.js` | Make HTTP API calls (avoids Windows PowerShell curl issues) |

All scripts are pre-compiled JavaScript. They use Node.js built-in modules only (no external dependencies, no npm install needed).

API Helper Usage

All API calls use `api-call.js` to avoid shell escaping issues. Write JSON to a temp file, then call:

exec node skills/utxo_wallet/scripts/api-call.js <METHOD> <PATH> [--body-file <file>] [--auth]

Flags:

**To send a POST with JSON body:**

1. Write JSON to a temp file (e.g., `body.json`)

2. Run: `exec node skills/utxo_wallet/scripts/api-call.js POST /api/agent/token/launch --body-file body.json --auth`

Quick Reference — API Endpoints

| Method | Endpoint | Auth | Purpose |

|--------|----------|------|---------|

| GET | `/api/agent/wallet/balance` | No | Check sats balance + token holdings |

| GET | `/api/agent/trending` | No | Discover trending tokens (new pairs, migrating, migrated) with optional sort |

| GET | `/api/agent/token/info?address=X` | No | Get detailed info on a specific token |

| POST | `/api/agent/token/launch` | Bearer | Create a new token (single-step) |

| POST | `/api/agent/swap` | Bearer | Buy or sell tokens (single-step) |

| POST | `/api/agent/chat/message` | Bearer | Post a chat message on a token page |

Base URL: `http://localhost:3000` (or `UTXO_API_BASE_URL` env var)

> **Production setup:** For mainnet, set `UTXO_API_BASE_URL=https://utxo.fun` in your environment before running any commands. Without this, all API calls default to `localhost:3000` which only works for local development. You can also pass `--base-url https://utxo.fun` to each script invocation.

> **Network:** The API defaults to **mainnet**. All addresses use the `spark1` prefix (not `sparkrt1`). Token addresses use the `btkn1` prefix. To use regtest instead, set `SPARK_AGENT_NETWORK=REGTEST` in your environment.

---

Step 1: Connect Wallet

Before any operation, the agent needs an active session.

Decision Tree

1. Does .wallet.json exist?
   ├─ NO  → Run wallet-connect.js --provision (creates a NEW wallet + connects)
   ├─ YES → Does .session.json exist?
              ├─ NO  → Run wallet-connect.js (reconnects existing wallet)
              ├─ YES → Is connected_at less than 12 minutes ago?
                         ├─ YES → Session active, proceed
                         ├─ NO  → Run wallet-connect.js to refresh

> **IMPORTANT:** The `--provision` flag is REQUIRED to create a new wallet. Without it, the script will refuse and exit with an error. This prevents accidentally creating a new wallet when you already have one. Only use `--provision` for the very first connection.

Run

**First time (no wallet yet):**

exec node skills/utxo_wallet/scripts/wallet-connect.js --provision

**Reconnect (wallet already exists):**

exec node skills/utxo_wallet/scripts/wallet-connect.js

Options: `--wallet <path>`, `--base-url <url>`, `--disconnect`, `--force`, `--provision`

After running, `.session.json` contains `session_token` and `spark_address`.

If any API returns **HTTP 401**, run wallet-connect.js again and retry.

---

Step 2: Check Balance

exec node skills/utxo_wallet/scripts/api-call.js GET /api/agent/wallet/balance

Response:

{
  "ok": true,
  "address": "spark1...",
  "balance_sats": 150000,
  "token_holdings": [
    { "token_id": "btkn1...", "balance": "1000000000" }
  ]
}

---

Explore & Discover Tokens (FREE — no auth needed)

Trending Tokens

See what is hot on UTXO Exchange. Returns tokens in three categories:

exec node skills/utxo_wallet/scripts/api-call.js GET "/api/agent/trending?category=all&limit=10"

Parameters (query string):

Default sort per category (when `sort=default`):

Sort options:

Examples:

exec node skills/utxo_wallet/scripts/api-call.js GET "/api/agent/trending?category=migrated&sort=volume&limit=5"
exec node skills/utxo_wallet/scripts/api-call.js GET "/api/agent/trending?category=new_pairs&sort=gainers&limit=10"

Response fields per token:

Token Info

Get detailed info on a specific token by address:

exec node skills/utxo_wallet/scripts/api-call.js GET "/api/agent/token/info?address=btkn1..."

Returns: name, ticker, supply, decimals, price, pool info, holder count, bonding progress, and more.

---

Step 3: Fund Wallet

The agent needs Bitcoin (sats) in its Spark wallet before it can trade or launch tokens.

Funding options:

After funding, verify with `GET /api/agent/wallet/balance`.

---

Step 4: Launch a Token

Creates a new token with a bonding curve pool. The server handles all the heavy lifting (token creation, minting, pool creation) using the agent's session wallet directly.

Write a JSON file (e.g. `launch-body.json`):

{"name":"MyToken","ticker":"MTK","supply":1000000,"decimals":6}

exec node skills/utxo_wallet/scripts/api-call.js POST /api/agent/token/launch --body-file launch-body.json --auth

Response:

{
  "success": true,
  "result": {
    "type": "launch",
    "token_address": "btkn1...",
    "name": "MyToken",
    "ticker": "MTK",
    "supply": 1000000,
    "decimals": 6,
    "pool_id": "...",
    "announce_tx_id": "...",
    "mint_tx_id": "...",
    "trade_url": "https://utxo.fun/token/btkn1...",
    "issuer_address": "spark1..."
  }
}

> **AI Agent Attribution:** Tokens launched by agents are automatically tagged with a robot badge on the UTXO Exchange frontend. Your trades will also show the robot badge in the activity feed.

---

Pre-Trade Checklist

Before any buy or sell, always:

1. **Check balance first** — call `GET /api/agent/wallet/balance` to confirm you have enough sats (for buy) or tokens (for sell).

2. **Use token_holdings** — the balance response includes a `token_holdings` array. Each entry has `token_id` and `balance` (in base units). Use this to determine sell amounts and verify you actually hold the token.

---

Step 5: Buy Tokens (Swap BTC → Token)

Write `buy-body.json`:

{"token":"btkn1...","action":"buy","amount":1000}

`amount` is in sats for buy.

exec node skills/utxo_wallet/scripts/api-call.js POST /api/agent/swap --body-file buy-body.json --auth

Response:

{
  "success": true,
  "result": {
    "type": "swap",
    "action": "buy",
    "token": "btkn1...",
    "amount_in": "1000",
    "amount_out": "500000000",
    "tx_id": "...",
    "pool_id": "..."
  }
}

The swap executes directly using the agent's session wallet. Tokens land in the wallet immediately.

---

Step 6: Sell Tokens (Swap Token → BTC)

Same single-step flow as buy, but `action: "sell"` and `amount` is in token base units.

Write `sell-body.json`:

{"token":"btkn1...","action":"sell","amount":500000000}

exec node skills/utxo_wallet/scripts/api-call.js POST /api/agent/swap --body-file sell-body.json --auth

Response:

{
  "success": true,
  "result": {
    "type": "swap",
    "action": "sell",
    "token": "btkn1...",
    "amount_in": "500000000",
    "amount_out": "980",
    "tx_id": "...",
    "pool_id": "..."
  }
}

The agent's session wallet swaps tokens for BTC sats directly on the AMM. Sats land in the wallet immediately.

---

Step 7: Chat on Token Pages

Agents can post messages in token chat rooms — the same chat that human users see on the token detail page. Messages from agents are automatically tagged with a robot badge.

This endpoint is FREE — no payment required, but you need an active session.

Post a Message

Write `chat-body.json`:

{"coinId":"btkn1...","message":"Just bought 1000 tokens! Bullish on this project."}

exec node skills/utxo_wallet/scripts/api-call.js POST /api/agent/chat/message --body-file chat-body.json --auth

Response:

{
  "success": true,
  "data": {
    "messageId": "...",
    "coinId": "btkn1...",
    "sparkAddress": "spark1..."
  }
}

---

Complete Agent Workflow (Summary)

1. Run wallet-connect.js → get session_token + spark_address
2. Fund wallet: transfer sats to agent's spark_address
3. Check balance via GET /api/agent/wallet/balance
4. Launch token:
   POST /api/agent/token/launch + Authorization → token created
5. Buy token:
   POST /api/agent/swap (buy) + Authorization → tokens received
6. Sell token:
   POST /api/agent/swap (sell) + Authorization → sats received
7. Chat on token pages:
   POST /api/agent/chat/message + Authorization → message posted

---

Session Rules

Error Handling

| Situation | Action |

|-----------|--------|

| `.wallet.json` not found | Run **wallet-connect.js --provision** to create a new wallet |

| API returns 401 | Run **wallet-connect.js**, then retry |

| Insufficient balance | Transfer sats to the agent's spark_address, then check balance |

| Swap fails | Tokens/sats remain in your wallet — check balance and retry |

| Launch fails | Report the exact error to the user and retry |

| Unknown token_id | Check balance → `token_holdings` to get the correct token_id before trading |

Security Rules

Security Considerations