# Agent Context (for LLMs) (/docs/ai-context)



> **For AI agents.** This page is domain context for an LLM using the Delta
> Exchange MCP tools. It explains how Delta's instruments and the tool responses
> are structured so you interpret data correctly. It is not human onboarding;
> for that, start at the [Quickstart](/docs). Read exact, live numbers (prices, fees,
> funding rates, contract specs) from the tools; do not assume them from this
> page. All output is informational, not investment advice. If the trading tools
> are available, see [Trading behavior](#trading-behavior) before placing
> anything.

## Instruments and symbols [#instruments-and-symbols]

Delta Exchange lists these `contract_types`: `perpetual_futures`, `futures`,
`call_options`, `put_options`, `spot`.

* **Perpetual futures**: no expiry; symbol is `UNDERLYING` + quote, e.g.
  `BTCUSD`, `ETHUSD`. Tethered to a spot index via funding.
* **Futures**: dated; settle at expiry against the index.
* **Options**: symbol format `{C|P}-{UNDERLYING}-{STRIKE}-{DDMMYY}`. Example:
  `C-BTC-66400-010824` = a **Call** on **BTC**, strike **66400**, expiring
  **01 Aug 2024**. `P-...` is a put.
* **Spot**: direct asset pairs.

Resolve full metadata for any symbol with `get_product` (tick size, contract
value, settlement asset, leverage caps, state). Discover symbols with
`list_products` / `list_tickers`.

## Expiries (critical date-format gotcha) [#expiries-critical-date-format-gotcha]

Two tools take expiry dates in **different formats**:

| Tool                | Field         | Format       |
| ------------------- | ------------- | ------------ |
| `get_options_chain` | `expiry_date` | `DD-MM-YYYY` |
| `list_products`     | `expiry`      | `YYYY-MM-DD` |

Mixing these up is a common failure. Delta offers daily, weekly, and monthly
options expiries depending on the underlying.

For expired/settled instruments, use `get_settlement_prices` (or
`list_products(states=["expired"])`). Each product carries `settlement_time`
and `settlement_price`. Use these for post-expiry P\&L reconciliation.

## Contracts and sizing [#contracts-and-sizing]

* **`size` is signed**: positive = long, negative = short.
* Each contract represents `contract_value` units of the underlying (e.g. a BTC
  contract may be `0.001` BTC; read it from `get_product`).
* **Notional exposure** (especially for options):

  ```
  notional_usd = abs(size) * contract_value * index_price
  ```

  Use **`index_price`** (spot of the underlying), **not `mark_price`**. For an
  option, `mark_price` is the option *premium*, so multiplying by it gives the
  premium value, not the underlying exposure. Example: a short BTC call with
  `size` 10, `contract_value` 0.001, BTC index 54,270 → notional =
  `10 * 0.001 * 54270 = $542.70`, not the \~$7.60 the premium would imply.

## Price types [#price-types]

* **Index price**: composite spot built from multiple exchanges; underlies
  futures/options. Inspect composition with `get_indices` (constituent
  exchanges, weights, `index_type` ∈ `spot_pair` / `fixed_interest_rate` /
  `floating_interest_rate`).
* **Mark price**: fair value used for margin, liquidation, and unrealised P\&L.
  For options this equals the option premium.
* **Last price**: last traded price (from `get_ticker`).

## Positions and P\&L [#positions-and-pl]

* `get_positions` returns only `entry_price` and `size` (lightweight).
* `get_margined_positions` returns the analytical fields: `unrealized_pnl`,
  `realized_pnl`, `realized_funding`, `margin`, `mark_price`,
  `liquidation_price`, `index_price`. Use this for risk and P\&L.
* **Short-option P\&L note:** the upstream API returns the unsigned premium value
  for short-option `unrealized_pnl`. The MCP tool patches it client-side as
  `(mark_price - entry_price) * size * contract_value` with signed `size`. Long
  options and futures pass through unchanged.

## Funding (perpetuals) [#funding-perpetuals]

Funding is a periodic payment exchanged between longs and shorts that tethers a
perpetual's price to its index. As a convention, positive funding means longs
pay shorts; negative means shorts pay longs.

* Current funding rate: `get_ticker`.
* Historical funding (OHLC over the rate): `get_funding_history`.
* Funding you have actually paid/received accrues into `realized_funding` on
  `get_margined_positions`.

Read the live rate and Delta's documented funding interval from the data and
official docs; do not assume a fixed number here.

## Fees [#fees]

Delta uses a maker/taker fee model, and options have a separate fee schedule
from futures. Exact rates vary by instrument, tier, and jurisdiction and may be
capped. **Do not fabricate fee numbers.** If a user needs fee figures, direct
them to Delta's official fee schedule, or compute realised costs from their own
`get_fills` records (which reflect actual fees charged) rather than estimating.

## Margin [#margin]

* Margin mode (isolated vs cross) is in `get_trading_preferences`.
* `get_wallet_balances` fields: `asset_symbol`, `balance`, `available_balance`,
  `position_margin`, `strategy_blocked_amount`.
* `strategy_blocked_amount` is collateral reserved by an active Algo Marketplace
  strategy subscription. It is **normal**; do not flag it as a risk or anomaly.

## Time units (frequent bug source) [#time-units-frequent-bug-source]

| Tool group                                                          | Unit             |
| ------------------------------------------------------------------- | ---------------- |
| Candle / OHLC / funding / OI / mark-price history (`start`, `end`)  | **Unix seconds** |
| Fills, orders, wallet transactions (`start_time_us`, `end_time_us`) | **microseconds** |

Passing the wrong unit in a time filter silently returns empty results.

## Pagination and bulk data [#pagination-and-bulk-data]

* Paginated tools return a `meta.after` cursor; pass it back to fetch the next
  page. Caps: `list_products` page\_size ≤ 500; fills/orders/wallet ≤ 200.
* For a user's **full** fills history (tax, accounting, backtests), prefer
  `bulk_fills_export` (writes a CSV) over looping `get_fills`.

## Resolutions [#resolutions]

Candle/history tools accept: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`,
`6h`, `1d`, `1w`.

## Environments [#environments]

`DELTA_MCP_ENV` is `india_prod` (production) or `india_testnet` (testnet). An API
key only works in its matching environment.

## Credentials [#credentials]

A key can come from two places, read in this order: the MCP client's own
configuration first, then `~/.delta-exchange-mcp/config.env`, one file shared by
every MCP client on the machine. **A value the client sets always wins**, and an
empty field in the client means "not answered" and falls through to the file. A
key saved to the file while the client is overriding it has no effect, and
restarting does not change that.

The setup tools are always registered and need no key. `setup_credentials` opens a form
for the key that runs outside the conversation; call it whenever the user wants to
connect an account or replace a key, and never ask for a key or secret in the
conversation instead. It needs a client that renders in-chat forms, and it reports
back when the client cannot. `get_connection_status` reports whether a key is
configured and which environment it points at; it returns no key, secret, or
fingerprint. `save_credentials` is the form's own save call. It is
app-only, so do not call it. `uvx delta-exchange-mcp login`
is the terminal equivalent of the form and works on every client.

## Capability boundary [#capability-boundary]

The server's surface depends on whether a key is present:

* **No key:** the setup tools and the market-data tools.
* **Any valid key:** the account tools and the trading tools, together. There is
  **no withdrawal tool in any configuration.**

The tool list does not tell you what the key may do. A Read Data key lists
`place_order` exactly as a Trading key does, and Delta answers it with
`Unauthorized`. Do not
promise the user an order will go through, and do not tell them to enable a mode:
there is none. Report Delta's rejection as what it is, a key-permission problem.

Never fabricate a capability you don't have. If a write tool isn't present, say
so rather than pretending to place an order.

## Trading behavior [#trading-behavior]

Order placement is real and immediate. There is no rehearsal mode and no
confirmation step, so confirm intent with the user before you call a tool that
places, edits, cancels or closes anything.

* **Nothing is checked for you.** No size cap, no notional cap, no rehearsal, no
  local record of what was sent. Orders are sized in contracts, not coins.
* **No retries on failure.** Mutations are never auto-retried. If a write times
  out or errors, surface it; do **not** re-send, because the first attempt may
  have landed.
* **Product reference:** pass exactly one of `product_id` or `product_symbol`.
  `limit_order` requires `limit_price`, and `market_order` ignores one. Prices go
  to Delta exactly as you give them. Delta moves an off-tick price onto the
  product's tick, so the `limit_price` in the response is the one that applies.
* **Order-level flags** (`post_only`, `reduce_only`) are booleans here; the tool
  serializes them to Delta's `"true"`/`"false"` string enums for you.
* **Blast-radius tools.** `cancel_all_orders` with no filter cancels every open
  order; `close_all_positions` takes no arguments and closes the whole account,
  both margin scopes. Neither has a narrower form, so get the user's explicit
  instruction first and say plainly what it will affect.
* **Batches** are not capped here; the exchange's own limit still applies.
  Delta's response is returned unchanged, and when it carries fewer orders than
  were sent, the missing ones were not accepted: compare the lists and report
  which, rather than resending the batch.
* **No local log.** Delta's own order and fill history is the record of what
  executed. Point the user there.

Frame analysis as research, never advice, and remind the user to verify against
the official Delta Exchange app before acting.

## Install reference [#install-reference]

Canonical config shapes, for agents asked to install the server. The human
walkthrough is the [Quickstart](/docs). `DELTA_API_KEY` / `DELTA_API_SECRET`
are optional; omit both for market data only. A key with Trading permission
places real orders, and needs nothing else set.

Standard `mcpServers` shape — Cursor (`~/.cursor/mcp.json`), Windsurf
(`~/.codeium/windsurf/mcp_config.json`), Claude Desktop
(`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "delta-exchange-mcp": {
      "command": "uvx",
      "args": ["delta-exchange-mcp"],
      "env": {
        "DELTA_MCP_ENV": "india_prod",
        "DELTA_API_KEY": "your-api-key",
        "DELTA_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

CLI clients:

```bash
claude mcp add delta-exchange-mcp --scope user --env DELTA_MCP_ENV=india_prod -- uvx delta-exchange-mcp
codex mcp add delta-exchange-mcp --env DELTA_MCP_ENV=india_prod -- uvx delta-exchange-mcp
```

Client quirks: Antigravity (`~/.gemini/config/mcp_config.json`) and Gemini CLI
(`~/.gemini/settings.json`) take the standard `mcpServers` shape above. Zed
(`~/.config/zed/settings.json`) names the top-level key `context_servers` and
nests the launch under `"command": { "path": "uvx", … }`. VS Code
(`.vscode/mcp.json`) names it `servers` and each entry needs
`"type": "stdio"`. OpenClaw (`~/.openclaw/openclaw.json`) nests the entry as
`{ "mcp": { "servers": { … } } }`. Hermes (`~/.hermes/config.yaml`) is YAML
under `mcp_servers`. Codex (`~/.codex/config.toml`) and Grok Build
(`~/.grok/config.toml`) use TOML, table `[mcp_servers.delta-exchange-mcp]`;
Grok Build takes env as the sub-table `[mcp_servers.delta-exchange-mcp.env]`.

On Windows every `~/…` path above is the same file at `%USERPROFILE%\…` with
backslashes, and `.vscode/mcp.json` stays relative to the project. Zed is the
one exception: it reads `%APPDATA%\Zed\settings.json` there, not a translation
of its XDG path. Windows also changes the shell, not the config: PowerShell
reads a trailing `\` as a literal argument, so a multi-line
`claude mcp add` or `codex mcp add` needs a backtick for each line break. The
two commands above are single-line and run unchanged on every platform.