GEAC accepts trading ideas from any system capable of making an HTTP request. This page takes a developer from first contact to a bot running reliably in production. The full API reference is searchable online, with a PDF and an OpenAPI file built from the same source.

Version 1.1.0 · updated 30 October 2026 · every example is illustrative (Tuesday 2026-11-03, a normal trading day; $GEAC_API_KEY stands for your key, never paste a real one) · there is no test environment: every accepted idea is a production idea.

AUnderstand GEAC

GEAC is an alpha-capture platform. Contributors, human and automated, send ideas: a direction on a stock, a conviction and a hedge. GEAC never trades on them. It prices each idea after receipt, sizes it in a paper book, measures the return against the chosen hedge, and expresses the result as net P&L in US dollars on that paper size. Contributors are ranked on net P&L; bots have their own league. Every submission, valuation and closure is written to an append-only, hash-chained ledger that is never edited or backdated.

A bot therefore sends instructions about ideas, not orders: open a long or a short, change its conviction, close it. There is no price, size, order type or venue. There is no investment horizon: an idea stays open until the bot closes it, subject to a 15-minute minimum hold and an automatic review after 120 trading sessions.

The rules in one table

RuleValue
Eligible namesUS-listed stocks (NYSE or Nasdaq, any domicile, excluding ADRs of foreign companies) above $100m market value and $1m traded a day, plus every S&P 500 and Nasdaq-100 member. About 3,000 names. Reviewed monthly; a member stays in down to $75m / $0.75m. When a name leaves, your open idea in it becomes close only, highlighted in the owner's web app.
Instructionsnew (buy or sell), amend (conviction only), close (with a reason). A reversal is a close then a new.
PricingEntry at a five-minute bar fixed at receipt (the next bar boundary after receipt inside 09:30–15:55 New York; otherwise the next session's 09:30 bar), priced at that bar's VWAP about 90 seconds after the bar closes and shown on the site at once. Exit valued at the official close of the day the close is accepted. Details and caveats: Pricing lifecycle.
Minimum hold15 minutes from the start of the entry bar. An earlier close is refused with the time from which the idea may be closed.
Review120 trading sessions after entry the idea is closed automatically unless a person reconfirms it in the web app.
Limits50 new ideas per UTC day (operator may raise to 200), 100 open ideas, one open idea per name, 60 requests a minute and 500 an hour, one message per request, 64 KB per message, sent_at within 5 minutes.
IdentityOne bot is one strategy with one named owner. Related bots are declared and treated as a family. A materially different strategy is a new bot.
Provisional periodThree calendar months from joining, as implemented: ideas are priced and ranked but earn nothing. Earlier text said "the first full calendar quarter"; see the account lifecycle for the open decision.
ConductIdeas must come from the bot's own analysis of public information. No material non-public information, no copied recommendations, no ideas derived from GEAC's other contributors.

Fields, scoring and sizing in detail: Fields and scoring.

BGet connected

  1. Apply. At geacsystems.com/apply choose Automated strategy. Give the owner's name, email and firm, the bot's name and a description of the strategy, and accept the declarations.
  2. Wait for approval. The operator reviews the application and emails the decision. This is a human step with no fixed turnaround.
  3. Create the key. Sign in and open Profile → Bot Connection. The key (geac_…, 48 characters) is shown once. Creating another key replaces it immediately.
  4. Store it as a secret. Put it in an environment variable such as GEAC_API_KEY, never in source code, a URL or a chat. If it leaks, create a new key: the old one dies at once.
  5. Ping. GET /v1/ping with the key. Read your limits and compare server_time with your clock. Pings are free, unlimited and not recorded.
  6. Read section D before sending ideas. The client_ref discipline it describes is what keeps a bot safe when the network misbehaves.
curl https://geacsystems.com/v1/ping \
  -H "Authorization: Bearer $GEAC_API_KEY"
GET /v1/pingAuthenticated ping

Headers

Authorization: Bearer $GEAC_API_KEY

Response 200

{
  "status": "ok",
  "bot": "Example Bot",
  "owner": "A. Developer",
  "cohort": "provisional",
  "limits": {
    "ideas_per_day": 50,
    "open_ideas": 100,
    "requests_per_minute": 60,
    "requests_per_hour": 500,
    "max_signal_age_s": 300,
    "minimum_hold_minutes": 15,
    "review_sessions": 120
  },
  "today": {
    "new_ideas": 0,
    "messages": 0
  },
  "open_ideas": 0,
  "server_time": "2026-11-03T14:30:58+00:00"
}

Next: The key works. Read limits and server_time, compare server_time with your clock, then send a test new.

GET /v1/pingPing with a missing or unknown key

Headers

(none)

Response 401

{
  "detail": "missing or unknown API key; send it as 'Authorization: Bearer geac_...'"
}

Next: Fix the header or the key. Do not retry in a loop: an inactive (paused) account gets the same answer. Note the 401 body uses the detail shape, not status/code/reason.

CSubmit and close

One JSON object per POST /v1/ideas. Every message carries event, a unique client_ref and sent_at. The responses below are the real shapes; ids and times are illustrative.

Open a long

curl https://geacsystems.com/v1/ideas -X POST \
  -H "Authorization: Bearer $GEAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "new",
  "client_ref": "bot1-2026-11-03-0001",
  "sent_at": "2026-11-03T14:31:05Z",
  "symbol": "MSFT",
  "side": "buy",
  "conviction": 3,
  "hedge": "sector",
  "styles": [
    "technical",
    "news"
  ],
  "thesis": "Example thesis: price has crossed above its 20 and 50 day averages after a cloud revenue update.",
  "target_pct": 8,
  "stop_pct": 4
}'
POST /v1/ideasOpen a long (BUY) idea

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "new",
  "client_ref": "bot1-2026-11-03-0001",
  "sent_at": "2026-11-03T14:31:05Z",
  "symbol": "MSFT",
  "side": "buy",
  "conviction": 3,
  "hedge": "sector",
  "styles": [
    "technical",
    "news"
  ],
  "thesis": "Example thesis: price has crossed above its 20 and 50 day averages after a cloud revenue update.",
  "target_pct": 8,
  "stop_pct": 4
}

Response 200

{
  "status": "accepted",
  "event": "new",
  "idea_id": "i_1a2b3c4d5e6f",
  "client_ref": "bot1-2026-11-03-0001",
  "symbol": "MSFT",
  "side": "BUY",
  "received_at": "2026-11-03T14:31:05.412+00:00",
  "review_date": "2027-04-26",
  "pricing": "next 5-minute VWAP after receipt",
  "minimum_hold": "15 minutes",
  "earliest_close": "2026-11-03T14:50:00+00:00"
}

Next: Store idea_id against your client_ref. Entry bar: 09:35-09:40 New York (14:35-14:40 UTC). The idea may be closed from earliest_close (09:50 New York); it may be amended at any time.

Open a short

A SELL idea is its own position. It does not offset a BUY in the same name: with one open idea per name per bot, a SELL while a BUY is open is refused.

POST /v1/ideasOpen a short (SELL) idea with a market hedge

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "new",
  "client_ref": "bot1-2026-11-03-0002",
  "sent_at": "2026-11-03T14:32:40Z",
  "symbol": "TSLA",
  "side": "sell",
  "conviction": 2,
  "hedge": "market",
  "styles": "valuation"
}

Response 200

{
  "status": "accepted",
  "event": "new",
  "idea_id": "i_7f8e9d0c1b2a",
  "client_ref": "bot1-2026-11-03-0002",
  "symbol": "TSLA",
  "side": "SELL",
  "received_at": "2026-11-03T14:32:40.087+00:00",
  "review_date": "2027-04-26",
  "pricing": "next 5-minute VWAP after receipt",
  "minimum_hold": "15 minutes",
  "earliest_close": "2026-11-03T14:50:00+00:00"
}

Next: A SELL idea is a separate position. It does not close a BUY in the same name; one open idea per name per bot, so a SELL while a BUY is open would be refused.

Amend

POST /v1/ideasAmend conviction

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "amend",
  "client_ref": "bot1-2026-11-03-0003",
  "sent_at": "2026-11-03T15:05:12Z",
  "idea_id": "i_1a2b3c4d5e6f",
  "conviction": 4
}

Response 200

{
  "status": "accepted",
  "event": "amend",
  "idea_id": "i_1a2b3c4d5e6f",
  "client_ref": "bot1-2026-11-03-0003",
  "symbol": "MSFT",
  "side": "BUY",
  "conviction": 4,
  "review_date": "2027-04-26"
}

Next: Only conviction can change through the API. Amending does not move the review date and does not re-price the idea.

Close

POST /v1/ideasClose the long idea

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "close",
  "client_ref": "bot1-2026-11-03-0004",
  "sent_at": "2026-11-03T19:40:02Z",
  "idea_id": "i_1a2b3c4d5e6f",
  "reason": "thesis_realised"
}

Response 200

{
  "status": "accepted",
  "event": "close",
  "idea_id": "i_1a2b3c4d5e6f",
  "client_ref": "bot1-2026-11-03-0004",
  "symbol": "MSFT",
  "side": "BUY",
  "closed_at": "2026-11-03T19:40:02.655+00:00",
  "reason": "thesis_realised"
}

Next: closed_at is the acceptance time. The idea is valued at the official close of that date (16:00 New York) by the nightly job. A new idea in MSFT may be opened at once.

Reverse

Close, wait for the acceptance, then open the other side under a new reference. Sent together the two race, and if the new arrives first it is refused because the old idea is still open.

POST /v1/ideasReversal, step 2: open the opposite side after the close was accepted

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "new",
  "client_ref": "bot1-2026-11-03-0005",
  "sent_at": "2026-11-03T19:40:03Z",
  "symbol": "MSFT",
  "side": "sell",
  "conviction": 2,
  "hedge": "sector"
}

Response 200

{
  "status": "accepted",
  "event": "new",
  "idea_id": "i_3c4d5e6f7a8b",
  "client_ref": "bot1-2026-11-03-0005",
  "symbol": "MSFT",
  "side": "SELL",
  "received_at": "2026-11-03T19:40:03.120+00:00",
  "review_date": "2027-04-26",
  "pricing": "next 5-minute VWAP after receipt",
  "minimum_hold": "15 minutes",
  "earliest_close": "2026-11-03T20:00:00+00:00"
}

Next: Step 1 was the close above. Received at 14:40:03 New York, so the entry bar is 14:45-14:50 and earliest_close is 15:00 New York.

When a message is refused

Every refusal except 401 comes back as {"status":"refused","code":…,"reason":…,"client_ref":…}: a code your program acts on and a sentence a person reads. The owner sees the same reason on the dashboard.

HTTPMeaningCodes
200Accepted, or a duplicate of an accepted reference(status accepted), (status duplicate)
400Malformed requestbad_json, missing_field, bad_field
401Missing, unknown or inactive API key (body: {"detail": ...})—
403Permission refused by the permissions engine (not reachable for a valid bot today)not_allowed
413Body larger than 64 KBtoo_large
422Rule, timing or state refusalstale, clock, unknown_idea, not_open, side_mismatch, universe, rule, repeat_of_refused
429Rate limit; Retry-After header in secondsrate_limited
500Server fault; nothing was recorded unless the response says so—

The full code table, with whether each refusal is recorded against your reference, and an example of every one: Responses and status codes.

DOperate reliably

Your reference is your safety net

GEAC remembers every client_ref a bot has ever sent. A repeated reference gets the first outcome again, for ever, whatever the body: 200 duplicate with the idea_id if it was accepted, repeat_of_refused with the old reason if it was refused. So:

  • Write the reference to durable storage before the request leaves your process, with the full body. A crash between send and store must leave a record you can replay.
  • Resending the same reference is always safe. It can never make a second idea.
  • Never generate a new reference until the old one's outcome is known. After a timeout, replay the original reference and read the reply. Only then decide.
  • A refused reference stays refused. Once you have fixed the problem, send a new reference.
POST /v1/ideasRepeat of an accepted reference

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "new",
  "client_ref": "bot1-2026-11-03-0001",
  "sent_at": "2026-11-03T14:31:05Z",
  "symbol": "MSFT",
  "side": "buy",
  "conviction": 3,
  "hedge": "sector"
}

Response 200

{
  "status": "duplicate",
  "idea_id": "i_1a2b3c4d5e6f",
  "client_ref": "bot1-2026-11-03-0001",
  "first_received_at": "2026-11-03T14:31:05.412+00:00"
}

Next: Nothing new was created. The reply carries idea_id and first_received_at only; earliest_close and review_date are not repeated. Resend the same reference after any unknown outcome before deciding anything.

Retry rules

OutcomeSame reference again?Do
Connection failed before sendingyesRetry while sent_at is under 5 minutes old; then re-decide.
Timeout, dropped connection, 5xxyes, to find outMark unknown, replay the same reference, act on the answer.
429yes, after Retry-AfterNot recorded. Wait, resend the same message; new reference only if sent_at would be stale.
400 on event/client_ref, bad_json, 413n/aNot recorded. Fix and send.
400 on any other fieldnoRecorded. Fix and send under a new reference.
401noStop and alert a person. Header, key, or a paused account.
422 stale / clocknoDiscard the signal; fix the pipeline or the clock; new reference next time.
422 rule on a close (minimum hold)noKeep the intent; at earliest_close send the close with a new reference. Replaying the old one returns repeat_of_refused, not "still too early".
422 not_open / unknown_ideanoYour state and GEAC's disagree. Replay every unknown reference, rebuild positions, then act.
422 universenoDrop the name. If you hold it, only a close is accepted.

The complete decision table and two worked workflows: Idempotency and retries.

POST /v1/ideasClose refused: minimum holding period

Headers

Authorization: Bearer $GEAC_API_KEY
Content-Type: application/json

Request body

{
  "event": "close",
  "client_ref": "bot1-2026-11-03-0006",
  "sent_at": "2026-11-03T14:45:30Z",
  "idea_id": "i_7f8e9d0c1b2a",
  "reason": "price"
}

Response 422

{
  "status": "refused",
  "code": "rule",
  "client_ref": "bot1-2026-11-03-0006",
  "reason": "ideas are held for at least 15 minutes after their entry bar; TSLA can be closed from 09:50 New York time on 3 Nov"
}

Next: Keep the exit intent locally, wait until earliest_close, then send the close again with a new client_ref.

Clocks and days

  • GEAC's receipt time governs pricing and the age check. sent_at more than 300 s old is stale; more than 120 s ahead is clock. Keep NTP running and compare with server_time from /v1/ping.
  • Response times are UTC. Market rules are New York time. The daily limit resets on the UTC date, that is at 19:00 or 20:00 New York.
  • Received at or after 15:55 New York, an idea's entry bar is the next session's 09:30 bar, with the overnight exposure that implies. Received on a market holiday or after the 13:00 close of an early-close day, the idea is never priced today; hold such ideas for the next open. See Pricing lifecycle.

Knowing your own state

Gap. The API has no read endpoints: a bot cannot list its open ideas, fetch an idea, or look up a reference other than by replaying it. /v1/ping gives the open-idea count only. An idea closed by GEAC at review, or made close-only because its name left the universe, is discovered only when the next amend or close returns not_open or universe; nothing is emailed. The owner's dashboard highlights the affected idea. Keep your own ledger of references and positions, replay unknown references on restart, and compare your open count with /v1/ping. A proposed read-only contract, not implemented, is described under State and recovery.

Operating rules

Keep the key private. The operator may pause a bot for repeated authentication failures, excessive malformed messages, rule breaches or compliance concerns; inactivity rules (10 trading days inactive, 30 days paused) are operator policy applied by hand, and pings do not count as activity. A paused bot receives 401. Decisions are logged and communicated to the owner.

ETest and launch

There is no sandbox. /v1/ping is always safe. Every accepted POST /v1/ideas is a production idea on your bot's permanent record and counts against your daily limit. It can be closed, never deleted.
  1. Dry run offline. Use the reference client's built-in fake of the API, which follows every rule on this page, until your message log looks right.
  2. Prove the key with /v1/ping from an environment variable, and check server_time against your clock.
  3. One real idea. Send one new at low conviction in a name you are content to have on your record, then an amend, then a close after earliest_close. Confirm the three messages on the owner's dashboard.
  4. Prove recovery. Kill the process between send and store, restart, replay: expect 200 duplicate and an unchanged open_ideas count.
  5. Go live with alerts on 401, repeated stale/clock, and any not_open or unknown_idea.
  6. Keep the reference at hand: geacsystems.com/api-reference, searchable, with the change log.

Reference client

A small Python client with no third-party dependencies is published alongside this documentation (examples/geac_client/ in the GEAC repository): dry-run by default, key from GEAC_API_KEY, live mode only behind two explicit flags, a SQLite store written before each send, the retry table encoded as code, earliest_close respected locally, and reconcile() to replay unknown references after a restart. Its tests use the examples on this page. A separate optional file wires a simple moving-average signal to it purely to show the plumbing; it is not a strategy recommendation.

Support

Integration or account queries: ops@geacsystems.com, with your bot's name and the client_ref in question. Never send the key.