> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/developers/agent-skill.md).

# 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:

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

For Claude Code:

```bash
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](https://github.com/sodex-tech/sodex-python-sdk-public).

## 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](/documentation/for-developers/sdks/python-sdk-guide.md) 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:

```bash
export SODEX_PYTHON='/absolute/path/from/bootstrap/python'
export SODEX_CLI='/absolute/path/from/bootstrap/cli'
"$SODEX_PYTHON" "$SODEX_CLI" profile init demo --network testnet \
  --owner 0xOWNER --api-key-name registered-bot
"$SODEX_PYTHON" "$SODEX_CLI" --profile demo profile show
```

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](/documentation/for-developers/developers/trading/api-keys-and-nonces.md).

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:

```json
{"action":"orders","market":"perps","symbol":"BTC-USD","orders":[
  {"side":"buy","type":"limit","quantity":"0.01","price":"80000"}
]}
```

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

```bash
"$SODEX_PYTHON" "$SODEX_CLI" --profile demo plan --file intent.json
"$SODEX_PYTHON" "$SODEX_CLI" ops show OPERATION_ID
# Execute only the operation you reviewed and authorized:
"$SODEX_PYTHON" "$SODEX_CLI" --profile demo execute OPERATION_ID --confirm OPERATION_ID
"$SODEX_PYTHON" "$SODEX_CLI" ops reconcile OPERATION_ID
```

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](/documentation/trading-mechanics/take-profit-and-stop-loss-orders-tp-sl.md).

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](https://github.com/sodex-tech/sodex-python-sdk-public/blob/main/skills/sodex/references/commands.md) contains the full intent schemas, read commands, profile options and limitations.

## Resume after a timeout or restart

```bash
"$SODEX_PYTHON" "$SODEX_CLI" ops list
"$SODEX_PYTHON" "$SODEX_CLI" ops show OPERATION_ID
"$SODEX_PYTHON" "$SODEX_CLI" ops reconcile OPERATION_ID
```

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

```bash
npx skills update sodex -g
```

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:

```bash
npx skills remove sodex -g -y
```

The isolated runtime cache is separate from the installed skill. See the [skill setup reference](https://github.com/sodex-tech/sodex-python-sdk-public/blob/main/skills/sodex/references/setup.md) 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

* [Python SDK Guide](/documentation/for-developers/sdks/python-sdk-guide.md)
* [SDKs & Tools](/documentation/for-developers/sdks.md)
* [Trading Quickstart](/documentation/for-developers/developers/trading/quickstart.md)
* [Mirror Protocol Lifecycle](/documentation/for-developers/developers/mirror-protocol/lifecycle.md)
* [WebSocket Streams](/documentation/for-developers/api-reference/trading-api/websocket-v1.md)