> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Kalshi

> The official hosted REST lane, transient RSA credentials, and unchanged client-side SDK path.

## Step zero — from nothing to your first trade

Kalshi has two separate execution paths. The hosted execution service and the client-side SDK use
the same venue account, but they have different credential boundaries. Choose one deliberately.

1. **Create the account.** Sign up at [kalshi.com](https://kalshi.com/) and complete the venue's
   regulated identity and eligibility checks.
2. **Create credentials.** From the Kalshi API Keys page, generate an API key ID and its matching
   RSA private key. Save both immediately outside source control; the private key is not shown
   again. If your account uses subaccounts, record the non-negative integer subaccount you trade.
3. **Fund it.** Deposit USD into your regulated Kalshi account through the venue's supported rails.
   Kalshi holds that balance; Predictefy never holds or intermediates it.
4. **Choose the path.** Use `/v1/exec/kalshi/...` for the hosted lane described below, or
   `client.accounts.kalshi` when credentials must stay entirely inside your own process.
5. **Check access.** Eligibility remains venue-controlled and location-dependent. Confirm access
   before depositing or submitting an order.

## What you need first

### Hosted official REST lane — per-request credential transit

- **Registration:** Default-off behind the literal `KALSHI_EXECUTION_ENABLED=true` setting. Check
  `GET /v1/exec/venues` for the deployment's actual arming state.
- **Venue account:** A funded, identity-verified Kalshi account. Funds remain venue-custodied USD.
- **Credentials:** The caller supplies `apiKeyId` and `privateKeyPem` on each submit or refresh.
  `subaccount` is optional on submit and must be a non-negative integer.
- **Lifecycle:** Catalog-bound build, official V2 submit, cancel, and caller-initiated status
  refresh are supported. The server never retains credentials for background polling.
- **Funding:** Use Kalshi's regulated deposit and withdrawal rails. No Solana wallet, token mint,
  gas balance, or Predictefy escrow is involved.

:::caution[Hosted credential boundary]
The RSA private key crosses to the isolated execution service for one authenticated request. The
service validates stored order truth and strict field allowlists before reading it, signs only the
fixed Kalshi method and path in memory, and then discards the key and generated headers. Neither the
key ID, PEM, nor auth headers are stored or logged.
:::

### Client-side SDK lane — credentials remain local

`client.accounts.kalshi` is unchanged. Configure `venueCredentials.kalshi` with your `apiKeyId`
and `privateKeyPem`; the SDK signs and sends requests directly to Kalshi from your process, so those
credentials never reach Predictefy. It supports account reads, limit orders, market-as-IOC orders at
your price cap, amendments, cancellations, and batched create/cancel. Use this path when the local
credential boundary matters more than hosted orchestration.

## Build an official hosted order

`POST /v1/exec/kalshi/orders/build` accepts normalized catalog intent. It accepts no venue
credential and performs no venue write.

| Field         | Type                         | Required | Rule                                                                 |
| ------------- | ---------------------------- | -------- | -------------------------------------------------------------------- |
| `outcome`     | non-empty catalog id         | yes      | Market id with `outcomeSide`, or a direct catalog outcome id         |
| `outcomeSide` | `YES` or `NO`                | no       | Required only when `outcome` names the market rather than the outcome |
| `isBuy`       | boolean                      | yes      | Maps the selected outcome to Kalshi's YES-book `bid` or `ask`        |
| `price`       | number strictly between 0–1 | yes      | Must land exactly on a whole-cent probability                        |
| `size`        | positive integer             | yes      | Whole-contract count                                                  |
| `timeInForce` | `good-til-cancel`            | no       | Defaults to `good-til-cancel`                                         |

The server resolves the native ticker and binary side from catalog truth. The returned authless
order artifact has exactly these fields:

| Field                         | Wire shape                                      |
| ----------------------------- | ----------------------------------------------- |
| `ticker`                      | non-empty native Kalshi ticker                  |
| `client_order_id`             | server-generated UUIDv4                         |
| `side`                        | `bid` or `ask`                                  |
| `count`                       | fixed-point whole contracts, for example `5.00` |
| `price`                       | fixed-point cents, for example `0.4200`          |
| `time_in_force`               | `good_till_canceled`                            |
| `self_trade_prevention_type`  | `taker_at_cross`                                |

## Submit, cancel, and refresh

- **Submit:** Send `{executionId, apiKeyId, privateKeyPem, subaccount?}`. The service signs and
  POSTs only the stored artifact. Caller-supplied ticker, side, count, price, or order fields are
  rejected before signing.
- **Cancel:** Build a cancel from the owned execution, then submit the new cancel execution with
  fresh `apiKeyId` and `privateKeyPem`. The stored cancel artifact is `{order_id}` and the venue
  call is the official V2 DELETE order endpoint.
- **Refresh:** Send `{apiKeyId, privateKeyPem}` to
  `POST /v1/exec/kalshi/orders/{executionId}/refresh`. No `executionId` or `subaccount` belongs in
  the body because the execution is already named by the path.

Status mapping is conservative: `resting` and `pending_review` become `acked`; `executed` becomes
`filled`; `canceled`, `expired`, and `rejected` become `canceled`, `expired`, and `failed`.
Unrecognized venue status leaves the non-terminal execution at the safe `acked` fallback.

:::caution[Orders built before the official-API migration]
Pre-migration Solana-shaped stored artifacts are incompatible with the official REST contract.
Submit or cancel refuses them with `ARTIFACT_VERSION_CONFLICT` (409), implemented by
`ArtifactVersionConflictError`. Build a fresh order with a new `Idempotency-Key`.
:::