> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parlayx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every tool the ParlayX MCP server exposes, and the trading opt-in

Seventeen read tools register on every start. Four trading tools register only
behind the [opt-in](#trading-tools) below.

Every tool returns its payload twice: as `structuredContent`, typed against the
tool's output schema, and as the same JSON in a text block for clients that read
only text.

## Read tools

### Identity and discovery

| Tool                 | Returns                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `whoami`             | The calling key's actor, pod, read scope and capabilities. Says whether the key may trade         |
| `get_time`           | The ParlayX server clock, in Unix seconds                                                         |
| `list_sports`        | The sports carried on the discovery surface, with their ids                                       |
| `list_competitions`  | Competitions, optionally filtered to one sport                                                    |
| `list_events`        | The scheduled and live events in a competition                                                    |
| `list_event_markets` | An event's markets, each with its outcomes and the per-venue listings an order needs              |
| `lookup_market`      | The canonical markets behind one venue identifier: a `tokenId`, `ticker`, `conditionId` or `slug` |

`lookup_market` takes exactly one of the four identifiers. Supplying none or
more than one is rejected before the call leaves your machine.

### Orders, fills, positions and balances

The two venues carry the same five read tools each, because markets, orders and
balances are venue-scoped.

| Polymarket                   | Kalshi                   | Returns                                            |
| ---------------------------- | ------------------------ | -------------------------------------------------- |
| `polymarket_list_orders`     | `kalshi_list_orders`     | One page of the actor's orders, newest first       |
| `polymarket_get_order`       | `kalshi_get_order`       | One order, by its ParlayX order id                 |
| `polymarket_get_order_fills` | `kalshi_get_order_fills` | The fills recorded against one order, oldest first |
| `polymarket_list_positions`  | `kalshi_list_positions`  | The actor's open positions on that venue           |
| `polymarket_get_balance`     | `kalshi_get_balance`     | The actor's balance on that venue, in USD          |

The order-list tools return one page and a `nextPageToken`. Pass it back as
`pageToken` to read the next page. The Polymarket tools filter by `tokenId`, the
Kalshi tools by `ticker`, and both filter by lifecycle `status`.

<Note>
  Discovery listings report `venue` in upper case (`POLYMARKET`, `KALSHI`), while the tools are
  named `polymarket_*` and `kalshi_*`. Read the venue off the listing and pick the matching tool.
</Note>

## Trading tools

<Warning>
  These four tools place and cancel real orders against real money. Every one of them is annotated
  as destructive so your client can prompt before it runs. Keep a person in front of each order.
</Warning>

| Tool                      | Does                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `polymarket_submit_order` | Places a Polymarket order on a `tokenId`, either `MARKET` or `LIMIT`                  |
| `polymarket_cancel_order` | Cancels one open Polymarket order by its ParlayX order id                             |
| `kalshi_submit_order`     | Places a Kalshi order on a `ticker`, with a `YES` or `NO` side and a whole-cent price |
| `kalshi_cancel_order`     | Cancels one open Kalshi order by its ParlayX order id                                 |

They register only when both halves of a gate are satisfied:

<Steps>
  <Step title="You opt in">
    `PARLAYX_MCP_ALLOW_TRADING=1` is set in the same env block as your credentials.
  </Step>

  <Step title="The key may trade">
    The key itself carries the `trade` capability. Call `whoami` to see what your key carries.
  </Step>
</Steps>

Without both, the tools are not advertised, so nothing can reach them. Both are
read before the transport opens, so changing either one takes effect on the next
restart rather than mid-session.

Each submit tool accepts an optional `idempotencyKey`. Pass the same value again
to make a retry safe. Omit it and every call mints a fresh key, which means a
retry is a second order. Order shapes match the REST contract: see the
[Polymarket](/api-reference/polymarket/submit-order) and
[Kalshi](/api-reference/kalshi/submit-order) references for the field semantics
and units.

## Errors

A failed call comes back as a tool result rather than a protocol error, marked
as an error and carrying three fields:

* **`code`**, the stable error category, such as `INVALID_REQUEST`,
  `NOT_FOUND`, `INSUFFICIENT_BALANCE` or `UNAUTHORIZED`. See
  [Errors](/sdk/errors) for the full set.
* **`status`**, the HTTP status code.
* **`message`**, an explanation, and for the cases an agent can act on, what to
  do next.

Response bodies are left out, so nothing large or unexpected lands in the model's
context.

Some messages go further than the API's own. A `403` points at `whoami`. An
idempotency conflict says to read the original result rather than retry. An order
that could not be reconciled says to stop and read it back. A rejected signature
is diagnosed first: see [Troubleshooting](/mcp/troubleshooting).