unifai-network/unifai-sdk-js/unifai

UnifAI CLI

A CLI for searching and invoking services on the UnifAI network. Supports 40+ services across DeFi, token data, social media, web search, news, travel, sports, and utilities.

What it does

unifai enables you to:

• Search services: Find services and actions using natural language queries
• Invoke services: Execute actions with customizable parameters and retry logic
• Manage configuration: Configure API keys with multiple priority levels

Available service categories

• DeFi: Swap, lend, borrow, provide liquidity (Aave, Uniswap, Jupiter, Meteora, Pendle, Compound, 1inch, and more)
• Token & market data: Prices, OHLCV, security analysis (Birdeye, CoinGecko, DexScreener, DefiLlama, GoPlusSecurity)
• Wallet & chain data: Token balances across Solana, Ethereum, Base, BSC, Polygon
• Social media: Twitter/X search, user timelines, tweet threads
• Web search & news: General search, Google news, financial data (SerpAPI, Tavily)
• Travel: Flight and hotel search
• Sports: NBA scores, soccer results (ESPN)
• Utilities: Math, time, domain availability, Solana rent reclaimer

Installation

Install globally so the binary is available locally:

npm install -g unifai-sdk

Or use via npx (no install needed)

-npx -p unifai-sdk unifai <command>

Setup

Set your API key:

export UNIFAI_AGENT_API_KEY="your-key-here"

Or create a config file:

unifai config init
# Edit ~/.config/unifai-cli/config.yaml

Commands

Search for tools

Always returns JSON with full payload schemas (best for agents):

unifai search --query "solana swap"
unifai search --query "token price" --limit 5

Compact numbered list (strips schemas):

unifai search --query "solana" --no-schema

Invoke an action

unifai invoke --action "Solana--7--getBalance" --payload '{"address":"..."}'

With transaction signing:

unifai invoke --action "Solana--7--transfer" --payload '{"toWalletAddress":"...","amount":0.01}' --sign

Payload from file:

unifai invoke --action "MyAction" --payload @payload.json

Sign a transaction

unifai tx sign <txId>
unifai tx sign <txId> --json

Configuration

unifai config init          # Create config file
unifai config show          # Show current config and sources
unifai config show --json   # JSON output

Version

unifai version
unifai --version

Agent Workflow

CRITICAL: Always search before invoking. Each action has its own field names (e.g. toWalletAddress for Solana, recipientWalletAddress for Polygon). Do NOT guess field names — they will fail silently or return cryptic server errors.

1. Search to get the action ID and exact payload schema:

``bash unifai search --query "swap SOL to USDC" ``

1. Read the `payload` field in the JSON response. It contains every field name, type, and whether it's required. Use these exact field names.

1. Invoke with the correct payload:

``bash unifai invoke --action "Jupiter--5--swap" --payload '{"inputToken":"SOL","outputToken":"USDC","inAmount":0.1}' --sign ``

1. If --sign is used and the response contains a txId, the transaction is automatically signed and submitted locally.

Important: Field Names Are Not Guessable

Different actions use different field names for similar concepts. Examples:

Always use `unifai search` first and read the payload schema. Never guess field names.

Understanding Errors

• `Error: API key is required` — Set UNIFAI_AGENT_API_KEY env var
• `Error: ... private key is required` — Set SOLANA_PRIVATE_KEY or EVM_PRIVATE_KEY for signing
• `Error: RPC URL is required` — Public defaults are provided, but you can override with env vars (e.g. POLYGON_RPC_URL)
• Server-side errors (e.g. "error": "Failed to create transaction: ...") — Usually wrong field names or invalid values. Re-check the payload schema from unifai search
• `--sign` with no txId — Normal. The action didn't need signing; the response is returned as-is

Transaction Signing

Transaction signing is optional and requires private keys via environment variables:

• SOLANA_PRIVATE_KEY — Solana key (base58, JSON array, or path to keystore file from solana-keygen)
• EVM_PRIVATE_KEY — EVM key (hex, with or without 0x prefix). Used for Ethereum, Polygon, Base, BSC, Hyperliquid, and Polymarket

RPC URLs (optional, public defaults are provided):

• SOLANA_RPC_URL — default: https://api.mainnet-beta.solana.com
• ETHEREUM_RPC_URL — default: https://eth.llamarpc.com
• BASE_RPC_URL — default: https://mainnet.base.org
• BSC_RPC_URL — default: https://bsc-dataseed.binance.org
• POLYGON_RPC_URL — default: https://rpc-mainnet.matic.quiknode.pro

Public RPCs are rate-limited. Set your own RPC URLs for production use.

All signing happens locally within the CLI process. Private keys are used only by the local @solana/web3.js and ethers libraries to sign transactions before submission. The CLI source code is available at https://github.com/unifai-network/unifai-sdk-js/tree/main/src/cli.

Common Examples

# Step 1: Always search first to get the exact schema
unifai search --query "solana transfer"
 
# Solana transfer (uses toWalletAddress, not "to")
unifai invoke --action "Solana--7--transfer" \
  --payload '{"toWalletAddress":"...","amount":0.01}' --sign
 
# Jupiter swap on Solana
unifai invoke --action "Jupiter--5--swap" \
  --payload '{"inputToken":"SOL","outputToken":"USDC","inAmount":0.1}' --sign
 
# Polygon transfer (uses recipientWalletAddress)
unifai invoke --action "Polygon--160--transfer" \
  --payload '{"recipientWalletAddress":"0x...","amount":0.01}' --sign
 
# Polymarket - get open orders (read-only, but still needs signing)
unifai invoke --action "polymarket--127--getOpenOrders" --payload '{}' --sign
 
# Read-only actions don't need --sign
unifai invoke --action "Birdeye--174--RetrieveTheLatestPrice" \
  --payload '{"address":"So11111111111111111111111111111111111111112","chain":"solana"}'
 
# Search for any capability
unifai search --query "weather forecast"
unifai search --query "sports scores"

Security Notes

• Private keys: SOLANA_PRIVATE_KEY and EVM_PRIVATE_KEY are only needed for transaction signing.
• Local signing: All transaction signing happens locally in-process using @solana/web3.js and ethers. Private keys are never sent to external API.