Kalshi

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 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.

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.

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.