fuego

name	fuego
description	Local Solana agent wallet with local infra for transfers (SOL, USDC, USDT), Jupiter swaps, and x402 purch.
homepage	https://fuego.cash
version	1.4.0
metadata	{"openclaw":{"emoji":"🔥","requires":{"bins":["curl","node","cargo"],"env":[]},"optional":{"bins":[],"env":[]}}}

Fuego SKILL

Local Solana agent wallet with local infra for transfers (SOL, USDC, USDT), Jupiter swaps, and x402 purch.

Quick Start

1. Install fuego-cli

npm install -g fuego-cli

2. Create Wallet

fuego create

# Output:
# Address: DmFyLRiJtc4Bz75hjAqPaEJpDfRe4GEnRLPwc3EgeUZF
# Wallet config: ~/.fuego/wallet-config.json
# Backup: ~/.config/solana/fuego-backup.json

3. Install Fuego Project

Prerequisites: Rust 1.85+ and Cargo are required to build the server.

# For OpenClaw agents (auto-detects ~/.openclaw/workspace)
fuego install

# For manual installs (specify path)
fuego install --path ~/projects/fuego

4. Configure Jupiter API Key (Optional - for Swaps)

If you want to do token swaps via Jupiter, you need an API key:

1. Sign up at https://portal.jup.ag
2. Create a new API key (free tier available)
3. Add to your Fuego config at ~/.fuego/config.json:

{
  "rpcUrl": "https://api.mainnet-beta.solana.com",
  "network": "mainnet-beta",
  "jupiterKey": "your-jupiter-api-key-here"
}

Without this key, swaps will not work. Balance checks and transfers work without it.

5. Start Server

fuego serve

# Output:
# Fuego server running on http://127.0.0.1:8080

6. Show Address to Human

fuego address

# Output:
# Your Fuego Address
# Name: default
# Public Key: DmFy...eUZF

Share this address so humans can fund the wallet. They can send SOL from any Solana wallet (Phantom, Solflare, etc.).

7. Fund the Wallet

Option A: MoonPay (for fiat → crypto)

• Visit: https://buy.moonpay.com/?currency=SOL&address=YOUR_ADDRESS
• Minimum: ~$30 USD
• Instant to wallet

Option B: Manual transfer

• Human copies address from above
• Sends SOL from their wallet to your Fuego address
• SOL needed for transaction fees (0.001 SOL per tx)

---

Send Transactions

Use the CLI - this is the recommended approach:

fuego send <recipient> <amount> --token USDC --yes

This single command:

• Builds transaction with fresh blockhash
• Signs locally (zero network key exposure)
• Submits to chain with proper error handling
• Returns signature + explorer link
• Supports address book contacts
• Works with SOL, USDC, USDT via --token flag

Example:

fuego send GvCoHGGBR97Yphzc6SrRycZyS31oUYBM8m9hLRtJT7r5 0.25 --token USDC --yes

---

Token Swaps via Jupiter

Step 1: Get a Quote First

Always show the user the expected rate before executing:

fuego quote --input BONK --output USDC --amount 100000

Output shows:

• Input amount (with token decimals handled automatically)
• Expected output amount
• Price impact
• Route details

Step 2: Execute the Swap

After user confirms the quote:

fuego swap --input BONK --output USDC --amount 100000 --slippage 1.0

Parameters:

• --input - Input token symbol (SOL, USDC, BONK, etc.) or mint address
• --output - Output token symbol or mint address
• --amount - Amount in token units (e.g., 100000 for 100000 BONK)
• --slippage - Slippage tolerance in percent (default: 0.5%)

The swap script automatically:

• Fetches correct token decimals from on-chain
• Uses BigInt for precision (no floating point errors)
• Throws error if decimals cannot be determined (prevents incorrect amounts)

Prerequisites:

• Jupiter API key must be configured in ~/.fuego/config.json
• See Step 4 in Quick Start for setup instructions

---

Agent-Ready Architecture

Agent/Script
       ↓ POST /build-transfer-sol
Fuego Server (localhost:8080)
  • Builds unsigned transaction with fresh blockhash
  • Returns base64-encoded transaction + memo
       ↓ Unsigned Transaction
Agent/Script
  • Loads ~/.fuego/wallet.json (simple JSON, no password!)
  • Signs transaction locally
       ↓ Signed Transaction
Fuego Server (localhost:8080)
  • POST /submit-transaction
  • Broadcasts to Solana mainnet
       ↓ On-chain
Solana Network

Security Model:

• Private keys never leave your machine (client-side signing for all transfers)
• File permissions provide real security (chmod 600)
• No network key exposure (localhost-only server)
• Standard Solana format (compatible with CLI tools)

One Exception - x402 Payments: The /x402-purch endpoint handles the complete payment flow internally (including signing) because x402 requires server-side proof-of-payment generation. This is a deliberate security trade-off: the server temporarily accesses the private key only to sign the specific x402 payment transaction, then immediately clears it from memory. This enables seamless agent purchasing while maintaining the local-first architecture for all other operations.

---

API Reference

GET /wallet-address

Get the local wallet address dynamically.

curl http://127.0.0.1:8080/wallet-address

Response:

{
  "success": true,
  "data": {
    "address": "DmFyLRiJtc4Bz75hjAqPaEJpDfRe4GEnRLPwc3EgeUZF",
    "network": "mainnet-beta",
    "source": "wallet"
  }
}

POST /balance - Check SOL Balance

curl -X POST http://127.0.0.1:8080/balance \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Response:

{
  "success": true,
  "data": {
    "sol": 1.234567890,
    "lamports": 1234567890,
    "network": "mainnet-beta"
  }
}

POST /tokens - Check All Token Balances

curl -X POST http://127.0.0.1:8080/tokens \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Returns SOL + all SPL token balances (USDC, USDT, BONK, etc.)

POST /build-transfer-sol - Build SOL Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-sol \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "0.001",
    "yid": "agent-transfer-123"
  }'

Response:

{
  "success": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDAb...",
    "blockhash": "J7rBdM33dHKtJwjp...AbCdEfGhIjKl",
    "memo": "fuego|SOL|f:YOUR_ADDRESS|t:RECIPIENT|a:1000000|yid:agent-transfer-123|n:",
    "network": "mainnet-beta"
  }
}

POST /build-transfer-usdc - Build USDC Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-usdc \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "10.50",
    "yid": "agent-usdc-456"
  }'

POST /build-transfer-usdt - Build USDT Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-usdt \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "25.75",
    "yid": "agent-usdt-789"
  }'

POST /submit-transaction - Broadcast Signed Transaction

curl -X POST http://127.0.0.1:8080/submit-transaction \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "transaction": "BASE64_SIGNED_TRANSACTION"
  }'

Response:

{
  "success": true,
  "data": {
    "signature": "5J7XzY...9KpQrS",
    "explorer_link": "https://explorer.solana.com/tx/5J7XzY...9KpQrS?cluster=mainnet-beta"
  }
}

---

Agent Integration Patterns

For Agents Writing Code (Node.js, etc.)

Just call the CLI via subprocess. That's it.

The CLI handles everything: building, signing, submitting, error handling. Don't wrap it in a class — just use it directly.

Node.js/TypeScript:

import { execSync } from 'child_process';

// Send payment
const result = execSync(
  'fuego send GvCo... 0.25 --token USDC --yes',
  { encoding: 'utf-8' }
);
console.log(result);

Alternative: Raw API Integration (Not Recommended)

If you absolutely must use raw API calls instead of the CLI, use the endpoints documented below. But the CLI is strongly preferred.

---

Complete API Reference

GET /

Root endpoint - returns server status.

curl http://127.0.0.1:8080/

Response:

Fuego Server

GET /health

Health check endpoint.

curl http://127.0.0.1:8080/health

Response:

{
  "status": "healthy",
  "service": "fuego-server",
  "version": "0.1.0"
}

GET /network

Get the default network configuration.

curl http://127.0.0.1:8080/network

Response:

{
  "network": "mainnet-beta"
}

GET /wallet-address

Get the local wallet address dynamically.

curl http://127.0.0.1:8080/wallet-address

Response:

{
  "success": true,
  "data": {
    "address": "DmFyLRiJtc4Bz75hjAqPaEJpDfRe4GEnRLPwc3EgeUZF",
    "network": "mainnet-beta",
    "source": "wallet"
  }
}

POST /latest-hash

Get the latest blockhash for transaction building.

curl -X POST http://127.0.0.1:8080/latest-hash \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta"}'

Response:

{
  "success": true,
  "data": {
    "blockhash": "J7rBdM33dHKtJwjp...",
    "network": "mainnet-beta"
  }
}

POST /sol-balance - Check SOL Balance

curl -X POST http://127.0.0.1:8080/sol-balance \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Response:

{
  "success": true,
  "data": {
    "address": "YOUR_ADDRESS",
    "lamports": 105113976,
    "sol": 0.105113976,
    "network": "mainnet-beta"
  }
}

POST /usdc-balance - Check USDC Balance

curl -X POST http://127.0.0.1:8080/usdc-balance \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Response:

{
  "success": true,
  "data": {
    "usdc": 150.250000,
    "raw_amount": "150250000",
    "network": "mainnet-beta"
  }
}

POST /usdt-balance - Check USDT Balance

curl -X POST http://127.0.0.1:8080/usdt-balance \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Response:

{
  "success": true,
  "data": {
    "usdt": 75.500000,
    "raw_amount": "75500000",
    "network": "mainnet-beta"
  }
}

POST /tokens - Check All Token Balances

curl -X POST http://127.0.0.1:8080/tokens \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

Returns SOL + all SPL token balances (USDC, USDT, BONK, etc.)

Response:

{
  "success": true,
  "data": {
    "wallet": "DmFyLRiJtc4Bz75hjAqPaEJpDfRe4GEnRLPwc3EgeUZF",
    "network": "mainnet",
    "sol_balance": 0.105113976,
    "sol_lamports": 105113976,
    "token_count": 2,
    "tokens": [
      {
        "symbol": "USDC",
        "ui_amount": 28.847897,
        "decimals": 6,
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    ]
  }
}

POST /all-transactions - Get Transaction History

curl -X POST http://127.0.0.1:8080/all-transactions \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS", "limit": 20}'

Returns all wallet transactions. Fuego transactions (those with fuego| in the memo) are styled with rich details in the dashboard.

POST /build-transfer-sol - Build SOL Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-sol \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "0.001",
    "yid": "agent-transfer-123"
  }'

Response:

{
  "success": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAEDAb...",
    "blockhash": "J7rBdM33dHKtJwjp...AbCdEfGhIjKl",
    "memo": "fuego|SOL|f:YOUR_ADDRESS|t:RECIPIENT|a:1000000|yid:agent-transfer-123|n:",
    "network": "mainnet-beta"
  }
}

POST /build-transfer-usdc - Build USDC Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-usdc \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "10.50",
    "yid": "agent-usdc-456"
  }'

POST /build-transfer-usdt - Build USDT Transfer

curl -X POST http://127.0.0.1:8080/build-transfer-usdt \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "from_address": "YOUR_ADDRESS",
    "to_address": "RECIPIENT_ADDRESS",
    "amount": "25.75",
    "yid": "agent-usdt-789"
  }'

POST /submit-transaction - Broadcast Signed Transaction

curl -X POST http://127.0.0.1:8080/submit-transaction \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "transaction": "BASE64_SIGNED_TRANSACTION"
  }'

Response:

{
  "success": true,
  "data": {
    "signature": "5J7XzY...9KpQrS",
    "explorer_link": "https://explorer.solana.com/tx/5J7XzY...9KpQrS?cluster=mainnet-beta"
  }
}

POST /submit-versioned-transaction - Broadcast Versioned Transaction

curl -X POST http://127.0.0.1:8080/submit-versioned-transaction \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "transaction": "BASE64_VERSIONED_TRANSACTION"
  }'

POST /x402-purch - x402 Payment (Server-Side Signing)

Complete x402 payment flow including server-side signing. Used for Purch.xyz integrations.

curl -X POST http://127.0.0.1:8080/x402-purch \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mainnet-beta",
    "product_url": "https://amazon.com/dp/B071G6PFDR",
    "email": "[e-mail]",
    "shipping_name": "John Doe",
    "shipping_address_line1": "123 Main St",
    "shipping_city": "Austin",
    "shipping_state": "TX",
    "shipping_postal_code": "78701",
    "shipping_country": "US"
  }'

---

Security Best Practices

What Makes Fuego Secure

1. File Permissions = Real Security

   # Wallet files are chmod 600 (user read/write only)
   ls -la ~/.fuego/wallet.json
   # -rw------- 1 user user 658 Feb 18 15:01 wallet.json
   

2. Client-Side Signing (with one exception)

   • Private keys never sent over network (for transfers, swaps, etc.)
   • Signing happens locally in CLI/scripts
   • Server only sees signed transactions (public data)
   • Exception: x402 payments require server-side signing for proof-of-payment generation. Key is loaded only for that specific transaction, then cleared from memory.

3. Localhost-Only Server

   • Server binds to 127.0.0.1 (local only)
   • No external network exposure
   • No firewall configuration needed

4. Standard Format Compatibility

   # Compatible with Solana CLI tools
   solana-keygen pubkey ~/.fuego/wallet.json  # Works
   solana balance ~/.fuego/wallet.json        # Works
   

Agent Security Checklist

• Keep ~/.fuego/wallet.json secure (it's your private key!)
• Don't commit wallet files to version control
• Only run server on localhost (default behavior)
• Regularly backup ~/.config/solana/fuego-backup.json
• Verify transactions on Solana Explorer
• Monitor wallet balance regularly
• Use strong system-level user isolation

---

Troubleshooting

Common Issues

"Wallet not initialized" error

# Solution: Create wallet with fuego-cli
fuego create

"Server not running" error

# Solution: Start server
fuego serve

"Connection refused" error

# Check if server is running
curl http://127.0.0.1:8080/health

# If not running, start it
fuego serve

"Fuego server not found" error

# Solution: Install the fuego project
fuego install

"Transaction simulation failed" error

# Usual cause: Insufficient balance
# Check all token balances first
curl -X POST http://127.0.0.1:8080/tokens \
  -H "Content-Type: application/json" \
  -d '{"network": "mainnet-beta", "address": "YOUR_ADDRESS"}'

"Invalid signature" error

# Wallet file might be corrupted
# Restore from backup
cp ~/.config/solana/fuego-backup.json ~/.fuego/wallet.json

Version mismatch / unexpected behavior

# Ensure all components are up to date
fuego update

# This updates both fuego-cli and the fuego project
# Restart server after updating: fuego serve

---

Supported Tokens & Networks

Transfer Tokens (fuego send)

These tokens are supported by fuego send:

Token	Mint Address	Decimals	Status
SOL	Native	9	Live
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6	Live
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenEqw	6	Live

Swap Tokens (fuego swap / Jupiter)

fuego swap supports any token tradable on Jupiter, including:

• SOL, USDC, USDT (above)
• BONK, JUP, PYTH, RAY, ORCA
• Any SPL token with liquidity on Jupiter

See https://jup.ag for full token list.

Network Support

• mainnet-beta - Production Solana network
• devnet - Development/testing network
• testnet - Solana testnet (limited use)

---

Ready to build autonomous Solana agents? Start with Fuego.