Club competitions
Competition trading API
On this page
Members of a club competition on Kresmion. You need a free account, a place in the club, and an account in the season: your own in an individual competition, your team's in a team competition. Clubs start here: Kresmion for finance clubs.
- Create a key on the competition page: open the club's Competition tab, then the API view, then Create key. The first key you create in a season asks you to accept the price terms (see About the prices).
- One key, one account. A key trades the competition account it was created for: yours, or in a team competition your team's shared account. It never reaches another account or another season.
- Not the data API. The Kresmion data API on the developers page uses other keys (krm_...). A data key is refused here, and a trading key (kpt_...) is refused on the data API and on every other part of Kresmion.
Send the key on every request, in the header Authorization: Bearer kpt_.... Read it from an environment variable rather than writing it in your code, and keep it out of anything you share.
- A key is
kpt_followed by 40 characters. We show it once, when you create it, and keep only a fingerprint of it, so we cannot show it again. If you lose it or it leaks, revoke it and create another. - Each key has a name you choose (1 to 40 characters). On a team account every teammate sees the team's keys: their names, their first characters, who created each one and when it was last used.
- Up to 10 live keys per account and 5 per person in a season; one person creates at most 20 keys in 24 hours.
- Revoke a key from the same list: programs using it stop at once, and a revoked key never works again. Its creator, the team leader (for a team key) and the club's officers can revoke it.
- Answers are JSON. Every time is in UTC (ISO 8601,
+00:00); a session date such as2026-11-16is a New York trading day. Amounts are in the season's currency (base_ccy) unless a field names another (ccy,quote_ccy).
Every path starts with the base URL, https://kresmion.com/api/paper-api/v1. Query values follow the path, for example /bars?id=1&interval=1d&limit=20.
/accountThe account: value, cash, return, orders waiting, the order limits, the team (in a team competition), this key, and whether it can place orders.
/positionsOpen positions at the stored prices, cash by currency and the account value.
/seasonThe competition: dates, currency, starting cash, format, every rule (rules) and the rules card, one sentence per line (rules_card).
/ordersThe account's orders, newest first, each with its fill once it has one.
Parameters status: pending, filled, cancelled, rejected or expired. limit: 1 to 200, 50 by default.
/orders/{id}One order of this account. An order of any other account answers 404.
/orders201 with the new order, or 200 with the first order when its client_order_id was used before on this account.
Parameters A JSON body (see Order fields).
/orders/{id}Cancels an order that is still waiting and answers the order.
/fillsThe account's fills, newest first, and next_after (null on the last page).
Parameters limit: 1 to 200, 50 by default. after: the next_after of the previous page.
/instrumentsThe instruments of this competition, in id order, each with tradable and, when it is false, the reason; next_after (null on the last page).
Parameters q: symbol or name, up to 40 characters. asset_class: equity, etf, crypto or fx. limit: 1 to 1,000, 100 by default. after: the next_after of the previous page.
/quotesThe stored price of each instrument, its time and its kind; ids outside this competition come back in not_found.
Parameters ids: up to 50 instrument ids, separated by commas.
/barsStored prices over time, oldest first, with complete and a note when the list has gaps.
Parameters id: one instrument id. interval: 1d (default) or 1m. limit: 1 to 500 for 1d (100 by default), 1 to 1,000 for 1m (390 by default).
The body of POST /orders, the same as an order placed on the competition page. Every check of the website runs on it.
instrument_idRequired. An id from /instruments.
sideRequired. buy or sell; short and cover too where the season allows short selling (rules.shorting).
order_typemarket (the default), limit or stop. Limit and stop only where the season lists them in rules.order_types.
qty / notionalA market order takes exactly one of them: qty in units, or notional, an amount in the season's currency. A limit or stop order takes qty.
limit_price / stop_priceThe limit price of a limit order, the stop price of a stop order, in the instrument's quote currency (for a currency, the season's currency per unit).
tifLimit and stop orders only: day (the default) or gtc (until you cancel it, at most to the end of the season).
client_order_idRequired. Your own id for the order, 1 to 64 characters (see Sending an order twice).
Real answers from our test run of the API, times in UTC, the key prefix made up and long answers shortened where a note says so. Your ids, prices and dates will differ.
Read the account
GET /account answers 200
return_pct is a fraction (0.0125 is 1.25%). On a team account, team is {"id", "name", "trade_mode"}, for example {"id": 1, "name": "Alpha", "trade_mode": "open"}.
Place an order
POST /orders answers 201
Placed on a Monday at 10:05 New York time: the order fills at the 10:06 price (fills_after). source is api for every order sent with a key; placed_by is the key's creator.
Check an order once it filled
GET /orders/1 answers 200
Shortened: the answer is the whole order, as above. The test recorded decided_at and filled_at at its own run time; here they sit on the example's clock. price is the price you got, after the season's slippage, in ccy; notional_base and fee_base are in the season's currency; filled_at is when we recorded the fill.
Cancel an order
DELETE /orders/2 answers 200
Shortened. See How orders fill for when a cancel is still possible.
Read the positions
GET /positions answers 200
qty is negative for a short. weight_pct is a percent of the account. price is the stored price the position is valued at, here the previous session's close.
Page through the fills
GET /fills?limit=1 answers 200
Ask GET /fills?limit=1&after=3 for the next, older page; next_after is null on the last page.
Find an instrument
GET /instruments?q=SPY answers 200
q matches the start of a symbol or any part of a name, so other instruments can come back too: pick the one whose symbol is exactly the one you want. Results come in id order, at most limit per page.
Read stored prices
GET /quotes?ids=1,3,6,4,987654 answers 200
Asked on a Monday at 10:05 New York time: the SPY price is still Friday's close. Shortened: the crypto quote (id 3) and its attribution line are left out, and so is each quote's source, a short code for where the engine took the price. Id 4 is not part of this competition and 987654 does not exist.
Read prices over time
GET /bars?id=6 answers 200
Daily bars of stocks and ETFs carry the close and, where we have it, the volume; open, high and low are null.
Read the competition
GET /season answers 200
Shortened: rules holds every rule of the season (costs, limits, asset types) and rules_card the whole card. format is individual or teams.
An error
POST /orders answers 403
Python 3 and its standard library only. It reads the account, finds an instrument by its exact symbol, reads its stored price, places a market order sized in money and waits for the fill. Set your key first, in the terminal that runs it: export KRESMION_TRADING_KEY=kpt_... (Windows: set KRESMION_TRADING_KEY=kpt_...).
We ran this program on 17 November 2026 against a local stand-in of the API, with only the base URL changed. An order placed outside New York market hours fills at the next open, so the loop may wait for hours: you can stop the program and check the order later by its id.
From a terminal: read the account, find an instrument, place an order, check it and list the fills.
An order never fills at the price you read. It fills at the next price after it, by the season's rules, exactly like an order placed on the website. Your season's rules card (rules_card in GET /season) states them in full.
- US stocks and ETFs, during New York market hours (9:30 to 16:00 New York time): the opening price of the next whole minute after your order. An order at 10:12:37 fills at the 10:13 price.
- US stocks and ETFs, outside market hours: the official opening price of the next trading session.
- Crypto: the next 1-minute exchange price after your order, around the clock.
- Currencies: the next ECB reference rate, published at 14:15 Frankfurt time on working days.
- Limit and stop orders, where the season allows them: a limit fills only when the price trades through it, at your limit or better; a stop becomes a market order once the price reaches it. Both are checked on the 1-minute prices we record (the ECB rate for currencies), for the day or until you cancel them.
Every order carries fills_after, the earliest time of the price that fills it, and fills_label, its rule in words. We record a market order's fill within about 5 minutes, a limit or stop order on a stock within about 15. This is not a low-latency venue: build your program for minutes, not milliseconds. Costs and slippage apply as on the website (rules.costs).
Cancelling. An order can be cancelled until fills_after. After that, a market order answers 409 (its price is already set); a waiting limit or stop order comes back still pending with cancel_requested_at set, and the cancel takes effect from the next whole minute.
/quotes and /bars return the prices the competition engine already holds to value accounts and fill orders. They are not a live market data feed. Bring your own market data for your program's signals, and use this API to trade and to read your account.
- Stocks and ETFs: a quote is usually the last session's closing price (
kindclose or daily_close), even while the market is open. It is a 1-minute price only when the engine needed that minute for a fill. Always readas_of. - Crypto: an exchange price the engine refreshes every few minutes.
- Currencies: the ECB reference rate of the day (
ecb_fix), published once each working day. - Daily bars go back up to 500 sessions. For crypto they are the engine's 16:00 New York valuation, kept only for coins a competition held, so that list can have gaps.
- 1-minute bars exist only for the minutes the engine used (fills, order triggers and the daily valuation), for the current and the previous session: the answer says
complete: falsewith a note. Currencies have none. - Every quote says
Indicative, not your fill: your order fills at the next price, as above.
The price terms you accept with your first key in a season: Prices from this API are for trading this competition. Do not store, republish or share them.
Answers with crypto or currency prices carry attribution lines: keep them with those prices.
We can switch prices off on the API. /quotes and /bars then answer 503 prices_off, and orders, the account and positions keep working.
- 60 requests a minute and 20,000 a day (UTC) per key. Past either, the answer is 429
rate_limitedwith aRetry-Afterheader in seconds. Answers to a valid key carryX-RateLimit-Limit-Minute,X-RateLimit-Remaining-Minute,X-RateLimit-Limit-DayandX-RateLimit-Remaining-Day. - Invalid keys: after 10 unknown keys from one address in an hour, that address's unknown keys answer 429
too_many_bad_keysuntil the hour frees; a valid key is still served. A revoked or stopped key refused 10 times in an hour answers 429 the same way. - The competition's order limits are the website's, per account (teammates share them). Read them from
limitsinGET /accountinstead of writing them into your program:orders_per_daycounts the orders placed in the last 24 hours,pending_maxthe market orders waiting,resting_maxthe limit and stop orders waiting, andmin_notionalis the smallest order in the season's currency. Over a count limit the order answers 429order_limit; under the smallest order, 422invalid_order.
Every error has the same shape, with the HTTP status. The message is one plain sentence you can show a person; your program should act on code, never on the message.
missing_key401No Authorization: Bearer header.
wrong_key_type401A data API key (krm_...) was sent. This API takes trading keys only.
invalid_key401The key is malformed, unknown or revoked.
unauthorized401Rare: the request was refused before the key was read.
key_inactive403The key exists but stopped working. The message says why (see When a key stops working).
captain_approves403The team leader approves this team's orders: this key can read, but cannot place or cancel.
forbidden403This key cannot place or cancel orders for this account.
not_found404No such order or instrument for this account, or no such address. An order of another account also answers not_found.
method_not_allowed405This address does not take that method.
rejected409The competition refused the order or the cancel: the season has not started or is closed, not enough cash, a holding limit, no recent price, a price already set. The message names the rule.
conflict409Rare: a conflict outside the order rules.
invalid_order422The order breaks a sizing rule, for example the smallest order, or a limit order without a limit price.
invalid_request422The request does not match the API: a missing field, a wrong type, a value out of range. The message names the field.
invalid_parameter422A query value the API refuses: ids, a bars limit, control characters in q.
order_limit429Too many orders in the last 24 hours, or too many orders waiting.
rate_limited429This key made 60 requests in the last minute, or 20,000 today (UTC). Wait for Retry-After seconds.
too_many_bad_keys429Too many invalid keys from your address, or this revoked or stopped key was refused too often, in the last hour. Wait for Retry-After seconds.
bad_request400Rare: the competition could not read the request.
internal500Something went wrong on our side. Try again a little later.
prices_off503Prices are switched off on the trading API for now. Orders, the account and positions still work.
unavailable503Rare: the service is busy. Try again a little later.
errorotherRare: any other refusal. The message says what happened.
Every POST /orders carries a client_order_id you choose. When the same id comes again on the same account, nothing new is placed: the answer is 200 with the first order, even if the rest of the body changed. So when a request times out and you do not know whether it arrived, send it again with the same id, and use a new id for each new order. On a team account the ids are shared: two teammates' programs that send the same id get the same order.
In a team competition each team trades one shared account, and a key trades the team's account. Every teammate's orders count toward the same limits, and each order names who placed it (placed_by): for an order sent with a key, the person who created the key. The team leader or an officer sets one of two modes:
- Everyone trades: any teammate can create a key, and any teammate's key can place and cancel orders.
- Leader approves: teammates propose orders on the competition page and the team leader approves or rejects each one. Only the team leader can create a key (while the team has no leader, a teammate who is a club officer can). A teammate's key made while the team was open still reads the account, but placing or cancelling answers 403
captain_approves. A key never sends a proposal: it places the order or is refused.
An approved proposal is placed at the approval and fills at the next price after it, never at a price from when it was proposed. The standings show an API tag on any account, member or team, with a filled order placed through the API.
We check the key on every request. It stops working when:
- it is revoked (401
invalid_key). A revoked key never works again; - its creator leaves the team or the club, or is removed from it: their keys there are revoked at once;
- the team is disbanded: every key of its account is revoked;
- its creator's Kresmion account is suspended, or their API access is turned off;
- the season closes, the account is no longer active in it, or the club is closed.
A revoked key answers 401 invalid_key; in the other cases the answer is 403 key_inactive with a sentence that says which. The API view of the competition shows when each key was last used.
This is version 1 of the trading API (/v1 in the base URL). It is in beta and may change: we announce changes in your club space. Questions: inquiry@kresmion.com.