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:

--body-file <path> — read JSON body from a file
--auth — auto-read .session.json and send Authorization: Bearer header

To send a POST with JSON body:

Write JSON to a temp file (e.g., body.json)
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

utxo_wallet

Install via CLI (Recommended)