Spot Trading Skill

Local TypeScript CLI and skill package for spot trading through supported CEXs and RivrDEX on Vara Network. VARA remains a default example, but CEX commands support any allowed active pair and DEX commands support token aliases or Vara program addresses.

Install

Install from npm without cloning the repository:

npm install -g vara-trading-skill

DEX trading also requires vara-wallet >= 0.20.3:

npm install -g vara-wallet

Install the agent skill pack from GitHub:

npx skills add https://github.com/gear-foundation/vara-trading-skill/tree/master/skill-pack -g --all -y

The GitHub skill pack lives in skill-pack/. The repository root is the npm/TypeScript CLI project.

Then restart your agent session if it does not pick up newly installed skills immediately.

Start With An Agent

After installation, ask your agent:

Use vara-trading-skill and set up local trading.

The agent should run the local setup commands:

vara-agent init-config
vara-agent onboarding interactive

The agent should keep the interactive wizard running and answer its prompts from the user's choices. It should not turn onboarding into separate one-command-per-step messages unless interactive terminal control is unavailable.

init-config creates ~/.vara-trading-agent/.env if it does not exist. The agent may create the file, start onboarding, and validate setup, but it must never ask the user to paste API keys into chat. When credentials are needed, the user edits ~/.vara-trading-agent/.env locally.

npm install -g installs the executable CLI. npx skills add ... installs SKILL.md and the recipe files into supported agent runtimes so the agent can discover vara-trading-skill.

If the user installed only the npm package and their agent supports Codex-style local skill directories, they can also run:

vara-agent install-skills

Restart the agent session after installing skills if the runtime does not pick up new skills immediately.

Configure

The setup starts with the step-by-step onboarding wizard. The agent must explain setup choices before live trading:

vara-agent onboarding interactive

For non-interactive current-step output only when needed:

vara-agent onboarding

Continue through the wizard:

vara-agent onboarding understand
vara-agent onboarding choose-mode --mode cex_exchange
vara-agent onboarding choose-integration --integration mexc
vara-agent onboarding choose-integration --integration gateio
vara-agent onboarding choose-integration --integration coinbase
vara-agent onboarding choose-integration --integration mexc,coinbase
vara-agent onboarding choose-integration --integration gateio,coinbase
vara-agent onboarding choose-integration --integration all

For RivrDEX instead:

vara-agent onboarding choose-mode --mode wallet_dex
vara-agent onboarding choose-integration --integration rivrdex

For machine-readable output:

vara-agent onboarding --json

Active onboarding supports CEX trading on MEXC, Gate.io, and Coinbase plus wallet-based trading through RivrDEX on Vara Network. Every live mode requires its checklist, risk limits, validation, dry-run, and final confirmation. Crypto.com, Exolix, and Banxa remain planned integrations.

For custom exchange selection, use comma-separated exchange IDs such as mexc,coinbase, gateio,coinbase, or mexc,gateio.

Coinbase VARA note: VARA/USDC and VARA/USD are useful Coinbase market examples. VARA/USDT was not observed during testing, so run check-market before adding a Coinbase pair to live risk limits.

CEX local credential setup:

vara-agent init-config

init-config creates ~/.vara-trading-agent/.env if it does not exist. If the file already exists, it leaves it unchanged.

Edit:

~/.vara-trading-agent/.env

Trading API keys must have read + trade permissions only.

After CEX setup is complete:

vara-agent onboarding connect --credentials-local
vara-agent onboarding configure-risk --max-trade-size-usd 50 --allowed-assets VARA,USDT,USDC,USD --allowed-pairs VARA/USDT,USDC/USDT,VARA/USDC,VARA/USD --max-slippage-percent 1
vara-agent onboarding validate
vara-agent onboarding dry-run
vara-agent onboarding final-confirm --confirm

--allowed-assets is a comma-separated list of asset tickers, for example VARA,USDT,USDC,USD. --allowed-pairs is a comma-separated list of market symbols, for example VARA/USDT,USDC/USDT,VARA/USDC,VARA/USD. onboarding validate loads markets and fetches balances to test the configured API credentials.

RivrDEX setup uses an encrypted local vara-wallet account. The CLI includes the known mainnet deployment; re-verify it before enabling live swaps:

vara-wallet wallet create --name dex-agent

# Edit ~/.vara-trading-agent/.env:
# VARA_DEX_NETWORK=mainnet
# VARA_DEX_FACTORY=0x943b74e9655497ee984022c7ecd6c5016edacc8eaf3a372d81c95efa83dd3f21
# VARA_DEX_ACCOUNT=dex-agent

vara-agent onboarding choose-mode --mode wallet_dex
vara-agent onboarding choose-integration --integration rivrdex
vara-agent onboarding checklist --confirm
vara-agent onboarding configure-dex --network mainnet --account dex-agent
vara-agent onboarding configure-risk --max-trade-size-usd 50 --allowed-assets WVARA,WUSDT,WUSDC --allowed-pairs WUSDT/WVARA,WVARA/WUSDT --max-slippage-percent 1
vara-agent onboarding validate
vara-agent onboarding dry-run
vara-agent onboarding final-confirm --confirm

onboarding validate checks the installed vara-wallet version, local account, network connectivity, and factory. The following onboarding dry-run command automatically reads the first allowed pool and fetches a quote for 1 human input unit; it does not select an account, approve, sign, or submit. Wallet seeds, mnemonics, and passphrases must never be passed to vara-agent or pasted into chat.

Run

vara-agent init-config
vara-agent onboarding
vara-agent routes --side buy --asset VARA --quote USDT --amount 20
vara-agent check-market --provider mexc --symbol VARA/USDT
vara-agent check-market --provider coinbase --symbol VARA/USD
vara-agent ticker --provider mexc --symbol VARA/USDT
vara-agent ticker --provider coinbase --symbol VARA/USD
vara-agent orderbook --provider mexc --symbol VARA/USDT --limit 10
vara-agent balance --provider mexc
vara-agent open-orders --provider mexc
vara-agent orders --provider mexc
vara-agent watch --orders --provider mexc --symbols VARA/USDT --interval 5m --limit 50
vara-agent watch --orders --provider mexc --symbols VARA/USDT --order-id "<order-id>" --interval 30s --limit 50
vara-agent withdrawal-guide --provider mexc --asset USDT --network TRC20 --amount 10 --address-confirmed
vara-agent buy --provider mexc --symbol VARA/USDT --quote-amount 10 --mode dry-run
vara-agent limit-buy --provider mexc --symbol VARA/USDT --quote-amount 2 --price 0.000605 --mode dry-run
vara-agent limit-sell --provider mexc --symbol VARA/USDT --base-amount 1000 --price 0.000604 --mode dry-run
vara-agent sell --provider mexc --symbol USDC/USDT --base-amount 10 --mode dry-run
vara-agent dex-pairs --network mainnet
vara-agent dex-pool --token0 WUSDT --token1 WVARA --network mainnet
vara-agent dex-quote --token-in WUSDT --token-out WVARA --amount 10 --units human --network mainnet
vara-agent dex-wrap --amount 10 --units human --network mainnet --mode dry-run
vara-agent dex-unwrap --network mainnet --mode dry-run
vara-agent dex-swap --token-in WUSDT --token-out WVARA --amount 10 --units human --mode dry-run --network mainnet

balance returns a compact summary of non-zero balances only.

RivrDEX Trading

DEX commands delegate signing and on-chain interaction to vara-wallet; this project never reads wallet secrets. dex-pairs, dex-pool, and dex-quote are read-only.

Known Vara mainnet deployment:

• factory: 0x943b74e9655497ee984022c7ecd6c5016edacc8eaf3a372d81c95efa83dd3f21
• VARA/USDT pair: 0x038534fe3ec91c4a9b4074f14908bfeca6358da0515772a428d8c489fdd134a1
• WVARA token: 0x29c42c668012b1ce20720e4615229215023281ef4676fdc77bf047d7fbcb9d17
• WUSDT token: 0x4255ff4a87a4c13dc39f74ace8c4948bbef2f75fb639d66639a1cfcc99e6243e

The pool is shown as VARA/USDT by RivrDEX. vara-wallet addresses the tokenized assets as WVARA and WUSDT. The known mainnet factory is selected automatically; --factory remains available for an explicitly verified override. Testnet and local commands require their own factory and never fall back to the mainnet address.

RivrDEX cannot consume native VARA directly. Selling VARA requires wrapping it into WVARA before the swap; buying through this pool returns WVARA rather than native VARA. dex-wrap calls VftNativeExchange/Mint with no arguments and attaches the requested native VARA amount as message value. The verified vft_vara.idl is bundled with the package; --idl is available only as an explicit override.

The verified mainnet Pair call attaches a gas limit of 150000000000 by default. On Vara mainnet runtime spec 11000, valuePerGas=100, so it can reserve up to 15 VARA; the existential deposit is 1 VARA. The CLI therefore enforces at least 17 VARA of free native balance immediately before a mainnet swap. Before starting a native-input workflow that wraps N VARA, it enforces at least N + 18 VARA, leaving additional room for Mint, Approve, and extrinsic fees. Revalidate these constants after a runtime upgrade.

Preview the encoded call without selecting an account, transferring VARA, or submitting a message:

vara-agent dex-wrap --amount 10 --units human --network mainnet --mode dry-run

Live wrapping is a separate state-changing operation. It requires completed wallet_dex onboarding, WVARA in the allowed assets, a fresh WVARA/WUSDT quote, the native reserve, the onboarded account, and explicit confirmation. The CLI derives the USD risk value from the quote's WUSDT output. That confirmation may be the single confirmation for a fully disclosed native-VARA trade chain:

vara-agent dex-wrap \
  --amount 10 \
  --units human \
  --network mainnet \
  --account dex-agent \
  --mode live \
  --confirm

The low-level dex-swap command never wraps automatically; the native-VARA workflow invokes the separate wrapper commands around it.

For a user-facing swap involving native VARA, execute the commands as one disclosed, non-atomic workflow:

1. When native VARA is the input, call dex-wrap for the exact input or slippage-capped maximum.
2. Let dex-swap clear any older allowance, approve and verify the exact input or slippage-capped exact-output maximum, call the verified Pair with 150-billion gas, and clear any remaining allowance.
3. When native VARA is the output—or an exact-output sale leaves unused WVARA—call dex-unwrap to return WVARA to native VARA.

The stages are separate transactions and are not atomic. One explicit user confirmation may cover the whole disclosed chain when the account, network, assets, amount bound, slippage, USD estimate, ordered stages, and full BurnAll scope are shown in advance and remain unchanged. Every state-changing vara-agent workflow invocation still includes --confirm as a local interlock.

Verify balances after every submitted transaction. BurnAll consumes the account's full WVARA balance, including any WVARA that existed before the swap, so its total scope must be included in that confirmation.

To return WVARA to native VARA, use dex-unwrap. It calls VftNativeExchange/BurnAll, so it converts the account's entire WVARA balance. The CLI reads that balance and derives the risk value from a fresh WVARA/WUSDT quote. Live mode lets vara-wallet calculate gas automatically by default; --gas-limit is only a manual fallback:

vara-agent dex-unwrap \
  --network mainnet \
  --account dex-agent \
  --mode live \
  --confirm

dex-swap defaults to dry-run. In dry-run it fetches a quote only: it does not approve a token, sign anything, or submit a swap.

Live execution requires completed wallet_dex onboarding, the exact verified network/factory/account, an allowlisted directed pair, a USD-size estimate within the configured limit, acceptable slippage, and --confirm:

vara-agent dex-swap \
  --token-in WUSDT \
  --token-out WVARA \
  --amount 10 \
  --units human \
  --network mainnet \
  --account dex-agent \
  --slippage-bps 100 \
  --mode live \
  --confirm

Every live swap fetches a fresh quote before the risk check. The CLI derives the USD value from amountOutFormatted for WVARA -> WUSDT and amountInFormatted for WUSDT -> WVARA. --estimated-value-usd is required only when neither side is USD-like; when supplied for a USD-like pair, it may raise but never lower the quote-derived value.

For the verified mainnet pair, auto-approve is handled inside vara-agent: omit --skip-approve and the command reads the 32-byte owner ActorId, clears any old allowance, creates and verifies the exact raw allowance, invokes the typed Pair method with the default 150000000000 gas limit, and clears any remainder. This path bypasses the Pair gas-estimation failure. Pass --gas-limit only to use a different reviewed Pair limit.

--skip-approve is an expert option: the current allowance must already equal the freshly derived raw bound exactly. The CLI still verifies and clears it after the Pair attempt. Keep automatic gas calculation for BurnAll.

Withdrawal Flow

Withdrawals are supported as an explicit high-risk capability. They are disabled by default and require dedicated withdrawal API keys plus local allowlists.

Withdrawal commands currently support MEXC and Gate.io. Coinbase is active for CEX trading and read-only order workflows, not withdrawal automation.

Use withdrawal-guide to see the setup and risk checklist:

vara-agent withdrawal-guide --provider mexc --asset USDT --network TRC20 --amount 10 --address-confirmed

Use withdrawal-check before submitting anything:

vara-agent withdrawal-check --provider mexc --asset USDT --network TRC20 --amount 10 --address "<address>"

Dry-run a withdrawal:

vara-agent withdraw --provider mexc --asset USDT --network TRC20 --amount 10 --address "<address>" --mode dry-run

Live API withdrawal requires all of the following:

• VARA_AGENT_ENABLE_WITHDRAWALS=true
• dedicated withdrawal API key and secret, for example MEXC_WITHDRAW_API_KEY and MEXC_WITHDRAW_API_SECRET
• VARA_AGENT_ALLOWED_WITHDRAW_ASSETS
• VARA_AGENT_ALLOWED_WITHDRAW_NETWORKS
• VARA_AGENT_ALLOWED_WITHDRAW_ADDRESSES
• positive per-asset limit, for example VARA_AGENT_MAX_WITHDRAW_USDT=25
• explicit command flags --mode live --address-confirmed --confirm-withdrawal

Example live command:

vara-agent withdraw --provider mexc --asset USDT --network TRC20 --amount 10 --address "<address>" --mode live --address-confirmed --confirm-withdrawal

Withdrawals are irreversible once accepted by the exchange. Use address allowlists and a small test withdrawal first.

Order Management

Use open-orders to see currently active exchange orders. Use orders to fetch recent order history and grouped counts for open, closed, canceled, and other statuses. Use watch --orders to poll orders and print fill/status-change events as JSON lines.

If --symbols is omitted, the CLI uses the allowed pairs configured in onboarding risk limits.

vara-agent open-orders --provider mexc --symbols VARA/USDT,USDC/USDT --limit 50
vara-agent orders --provider mexc --symbols VARA/USDT,USDC/USDT --limit 50
vara-agent watch --orders --provider mexc --symbols VARA/USDT,USDC/USDT --interval 5m --limit 50
vara-agent watch --orders --provider mexc --symbols VARA/USDT --order-id "<order-id>" --interval 30s --limit 50
vara-agent watch --orders --provider mexc --symbols VARA/USDT --interval 30s --limit 50 --once

The watcher is read-only polling. It does not run a backend, daemon, or automatic trading strategy. When --order-id is provided, the watcher stops automatically after that tracked order becomes closed, filled, canceled, cancelled, expired, or rejected. Use --keep-running only when you explicitly want polling to continue after the tracked order is finished.

Canceling an order is a real exchange action and requires the exact order id plus --confirm:

vara-agent cancel-order --provider mexc --symbol VARA/USDT --order-id "<order-id>" --confirm

Live Mode

Live mode sends real orders to the exchange.

Use only after onboarding and dry-run testing:

vara-agent onboarding final-confirm --confirm
vara-agent buy --provider mexc --symbol VARA/USDT --quote-amount 10 --mode live

Live orders are allowed only for pairs and assets configured in onboarding risk limits.

CEX API Key Safety

Create the key in the exchange API key section.

Gate.io setup:

• Open Security and set a Fund Password first
• It protects fund security; trading does not require fund password input by default
• Open API Key Management to create the Gate.io API key
• Create a dedicated API key for this agent
• Enable Read / View account data
• Enable Spot Trading
• IP whitelist is optional
• Copy the API Key and Secret Key shown by Gate.io
• Open ~/.vara-trading-agent/.env and fill these exact lines:

GATEIO_API_KEY=<paste Gate.io API Key here>
GATEIO_API_SECRET=<paste Gate.io Secret Key here>

• Secret Key may be shown only once; never paste it into chat
• Withdrawal permission is not part of normal trading setup. API withdrawals are high risk; enable them only with a separate dedicated withdrawal key if you explicitly want withdrawal automation.

MEXC setup:

• Click the account icon
• Select API Management
• Create a dedicated API key for this agent
• Enable Account Details
• Enable Trade
• Enable View Order Details
• Link IP Address is optional
• Copy the API Key / Access Key and Secret Key shown by MEXC
• Open ~/.vara-trading-agent/.env and fill these exact lines:

MEXC_API_KEY=<paste MEXC API Key / Access Key here>
MEXC_API_SECRET=<paste MEXC Secret Key here>

• Secret Key may be shown only once; never paste it into chat

Coinbase setup:

• Open Coinbase Developer Platform / Advanced Trade API key management
• Create a dedicated API key for this agent
• Scope the key to the portfolio this agent should trade from
• Enable View
• Enable Trade
• Do not enable Transfer permissions for normal trading setup
• IP whitelist is optional
• Copy the API Key name and API Secret shown by Coinbase
• Open ~/.vara-trading-agent/.env and fill these exact lines:

COINBASE_API_KEY=<paste Coinbase API Key name here>
COINBASE_API_SECRET=<paste Coinbase API Secret here>

• Secret may be shown only once; never paste it into chat
• Coinbase withdrawal/transfer automation is not part of normal trading setup

Required permissions:

• Read / View account data
• Trade / Spot trading

Withdrawal API key permissions:

• Enable withdrawal permission only on a dedicated withdrawal key if the user explicitly wants API withdrawals.
• Use exchange address allowlists and IP restrictions whenever available.
• Keep withdrawal keys separate from trading keys.

Create a separate API key only for this agent. Never paste API keys or secrets into chat. If the exchange supports IP whitelist and the agent platform provides a fixed IP, enable it. If there is no fixed IP, leave the whitelist disabled only if you understand the risk.

Use trading limits, a separate subaccount, and only funds you are willing to trade.

Release Scope

The active release supports MEXC, Gate.io, and Coinbase CEX trading plus RivrDEX quotes and explicitly confirmed on-chain swaps through vara-wallet. It includes local onboarding, risk allowlists, read-only market/account/pool checks, CEX order management, tracked-order watching, withdrawal checks, and explicitly confirmed API withdrawals for supported withdrawal providers. Crypto.com, Exolix real swap execution, Banxa checkout creation, 24/7 autonomous monitoring, conditional orders, arbitrage, and automatic route optimization remain future plans.