Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SoDEX Agent Skill

Connect your AI coding assistant to SoDEX with one install command. The sodex skill uses the official Python SDK and a bundled JSON command interface to query markets/accounts, preview and execute trading operations, and recover after timeouts or restarts. It also guides SDK integrations and funding workflows. It combines all nine SDK examples with the relevant SoDEX documentation.

Install

You need an Agent Skills-compatible assistant, Node.js/npm for the installer, Python 3.9 or later with venv and pip, Git, and network access. The unified CLI supports macOS and Linux; use WSL on Windows. The SDK and public connectivity check also work on native Windows.

For Codex:

npx skills add sodex-tech/sodex-python-sdk-public --skill sodex -g -a codex -y

For Claude Code:

npx skills add sodex-tech/sodex-python-sdk-public --skill sodex -g -a claude-code -y

Omit -g to install for the current project. For another compatible assistant, omit -a and choose it in the installer. Start a new assistant session if the skill is not discovered after installation.

Source: SoDEX Python SDK.

Make your first connection

Send this prompt to your assistant:

Use $sodex to connect to SoDEX and verify a live BTC perpetual quote on mainnet.

The assistant runs the skill's setup script, creates an isolated Python environment, installs the reviewed SDK, and queries public market data. This first query needs no wallet or API key. It does not submit an order or move funds.

A successful result includes the network, symbol, latest price, SoDEX as the source, and the observation time. Setup also returns the Python executable and SDK checkout paths, plus the bundled cli path, for subsequent commands. If the query fails, resolve the reported connectivity or symbol issue before continuing.

The skill pins SDK 0.2.1 plus trading-metadata fixes to source revision ce188ffa5971048489441de5c2f21020208f54d4. It retrieves the SDK examples automatically; no separate CLI package or MCP server is required. The fixes retain symbol filters and per-order Gateway errors for reliable preflight and batch results. See the Python SDK Guide for application integrations.

What you can ask

Workflow
Example prompt

Market data

“Use $sodex to show BTC perpetual price, depth, and the last 24 hourly candles.”

Account state

“Use $sodex to show balances, positions, and open orders for this wallet address.”

Trading integration

“Use $sodex to prepare a testnet limit-order example and explain how to track its fill.”

Order preflight

“Use $sodex to preview this order against the live symbol limits and my account, without submitting it.”

Take-profit and stop-loss

“Use $sodex to prepare an entry with attached TP/SL, or protect my existing BTC position.”

Amendments and batches

“Use $sodex to amend these resting orders and show each result separately.”

Leverage and margin

“Use $sodex to preview a leverage change or an isolated-margin adjustment.”

Recovery

“Use $sodex to find my last operation and reconcile it after the timeout without submitting it again.”

Public and account streams

“Use $sodex to subscribe to order updates and explain recovery after a disconnect.”

Deposits and transfers

“Use $sodex to discover USDC deposit routes and explain how to move Spot funds to Perps.”

Withdrawal tracking

“Use $sodex to check this withdrawal by its request hash without submitting it again.”

API keys

“Use $sodex to configure a dedicated key with trading and cancellation enabled.”

Builder fees

“Use $sodex to explain builder fee approval and prepare an attributed order.”

The skill uses the bundled commands for supported operations and the SDK's methods/examples for application development and other workflows. Specify the network and account for account-specific tasks, and the intended market, symbol, side, amount and price for trading.

Configure credentials when needed

Public market data needs no credentials. Account reads need an owner address and optionally an account ID. For trading, create a local encrypted profile using the Python and CLI paths returned by setup:

Run initialization in your terminal. It asks for the private key and keystore password through hidden prompts, encrypts the key using the standard eth-account keystore, and stores the profile in ~/.local/share/sodex-skill/. Directory permissions are 0700; profile and database permissions are 0600. profile show never returns the key or keystore. Use --watch-only instead of signing options for a keyless preview profile, or --account-id to choose a subaccount. Importing a profile does not register a key on SoDEX or submit a trade.

A secret manager can supply locally populated environment variables using --key-env SODEX_PRIVATE_KEY --password-env SODEX_SKILL_PASSWORD. The arguments are variable names, never secret values. Do not paste keys or passwords into the assistant conversation, shell history, or source control. Keep a secure backup through your existing process; losing the password prevents unlocking the key. SDK examples still support their documented environment variables; the SDK does not automatically load .env files.

Use a dedicated, revocable API key for routine trading. Key registration, revocation and builder-fee approval require the master wallet. An API-key permission bit disables the corresponding permission; omitting the mask enables all permissions. See API Keys and Nonces.

Before executing a write, the assistant establishes the authorized network, account, operation and parameters. Asking for setup or example code does not authorize live trading, key registration, approvals, transfers or withdrawals.

Preview, execute, and inspect JSON results

The assistant can create a JSON intent using your parameters instead of writing temporary Python. For example, a limit-order intent has this shape:

These values illustrate the schema; replace them with your intended trade and current market constraints. Save it as intent.json:

Planning is unsigned. It saves the account/network, normalized request, generated client order IDs, SDK payload and preflight snapshot. Checks cover account ownership, key permissions/expiry, symbol status, price/quantity precision and grids, lot/notional limits, price bands, target orders, TP/SL direction, reduce-only size, leverage limits and margin-mode restrictions. It also aggregates estimated Spot costs and estimates Perps opening margin when an established leverage/margin configuration is available. Execution rechecks current state and rejects a changed payload before signing.

Preflight is not a funds reservation or a full risk-engine simulation. Fee overrides, replacement reserve release, position netting, maintenance tiers, liquidation and maximum removable margin remain engine checks. Missing local estimates appear in the preview warnings. An accepted order is not a fill.

Action
Supported operation

orders

Single or 1–100 order batches on one Spot/Perps symbol; limit/market, GTC/IOC/GTX where supported

bracket

Perps entry with attached reduce-only TP/SL and native OCO behavior

tpsl

Mark-price TP/SL for an existing position; optional full-position sizing

amend

Replace resting GTC/GTX limit orders, including batches; modify one TP/SL target at a time

cancel

Single or batch cancellation using saved order/client IDs

leverage

Change Perps leverage and cross/isolated margin mode subject to current account constraints

margin

Add or remove margin from an isolated Perps position

Attached exits activate when the parent fills completely, or after a partial fill followed by system cancellation for insufficient margin. Manually canceling a partially filled parent also cancels the exits. Existing-position TP/SL orders are independent reduce-only stops; do not assume they form OCO. See TP/SL mechanics.

Commands return a versioned JSON envelope (schema_version, ok, result or error). Monetary values are strings; integers above 2^53-1 are strings to preserve large IDs. Every batch receipt keeps its own result code and error. Execution states distinguish accepted, partial, rejected and unknown. Exit codes are 0 for success, 1 for operational/non-accepted execution results, and 2 for invalid input or preflight failure. --help prints usage.

The command reference contains the full intent schemas, read commands, profile options and limitations.

Resume after a timeout or restart

The local SQLite journal records intent before sending and receipts afterward; it survives skill/runtime updates. A crash can leave submitting; a lost response leaves unknown. Reconciliation uses the saved account/network to read open orders, history, fills and account state without unlocking a key. It preserves the original outcome and adds observations. It never resubmits the operation; even a rejected operation cannot be executed a second time.

Missing records do not prove a write failed. Recovery reports possible truncation of its 500-open-order and 1,000-history/fill snapshots; use narrower history windows for busy accounts. A leverage or margin snapshot cannot prove whether a particular past adjustment ran. Investigate ambiguity before authorizing a new action.

The CLI persists nonces and locks each signer/network across processes sharing one state directory. Other applications, state directories or machines require separate signing keys or external coordination. The journal contains account activity; protect it along with the encrypted profiles.

Network and completion checks

  • Set SODEX_NETWORK explicitly for SDK workflows. Client.from_env() defaults to mainnet. Testnet supports trading, but Mirror funding APIs are mainnet-only.

  • Discover exact symbols on the selected network. For example, mainnet Spot returned vBTC_vUSDC when this skill was validated; do not assume the upstream examples' BTC/USDC label is accepted by Gateway.

  • An accepted order is not a fill, an indexed deposit is not confirmed credit, and a submitted withdrawal is not external settlement. Save identifiers and verify the relevant state before starting a dependent action.

  • After a timeout or WebSocket disconnect, reconcile REST state and history before retrying a signed write. Resume withdrawal tracking with the existing request hash or withdrawal ID.

Update and troubleshoot

The skill uses a reviewed SDK revision. Updating its instructions changes the runtime version only when the reviewed source pin changes.

If setup fails, check that Python, venv, pip and Git are available and that GitHub, the Python package index and the selected Gateway are reachable. Use the Python executable returned by setup for SDK commands. For a missing Spot symbol, query spot_symbols() on the selected network first.

To remove the global skill:

The isolated runtime cache is separate from the installed skill. See the skill setup reference for runtime paths and further diagnostics. Removing the installed skill or runtime does not remove profiles or the journal. Preserve the state directory to retain recovery history and encrypted keys.

Related documentation

PreviousDocumentation
NextMirror Protocol

Last updated