{
  "openapi": "3.1.0",
  "info": {
    "title": "GEAC bot API",
    "version": "1.1.0",
    "summary": "Two endpoints through which an automated strategy (a 'bot') sends trade ideas to GEAC.",
    "description": "GEAC pays contributors for the alpha in their trade ideas. A bot is a contributor account with `input_mode='bot'`; it authenticates with an API key and sends **one order per message** to `POST /v1/ideas`: `new`, `amend` or `close`. Everything then goes through the same intake as a person's idea (same limits, same pricing, same ledger, same emails).\n\nThis document describes **only verified, implemented behaviour** (code inspected 30 October 2026, commit 544489d). Where the implementation and the published prose disagree, the response is documented as actually returned and the disagreement is noted in the relevant description. See `x-changelog` for what changed between 1.0 and 1.1 and `x-proposed` for read endpoints that are **not implemented**.\n\n### Idempotency\nEvery `POST /v1/ideas` message carries a bot-chosen `client_ref` (1–64 characters, unique per bot). The server looks the reference up **before** it validates `sent_at` or anything else. A repeat of an accepted reference returns `200 {\"status\":\"duplicate\", ...}` with the original `idea_id` and the time of first receipt; a repeat of a refused reference returns the original HTTP status with code `repeat_of_refused` and the original reason. Refusals are cached **indefinitely** (nothing prunes `bot_messages`) and the payload of a repeat is **ignored**: the same reference always gets the same answer whatever the body. Only 401, 413, 400 `bad_json`, 400 errors on `event`/`client_ref` themselves and 429 are *not* recorded against a reference.\n\n### Rate limits\n`/v1/ideas` only: 60 requests per rolling 60 s and 500 per rolling 3600 s, per bot, counted in process memory (a deploy resets them). A rate-limited call is answered 429 with a `Retry-After` header and is neither recorded nor cached. `/v1/ping` is not rate limited and is not recorded anywhere (it does not count as activity).\n\n### Clocks\nThe server's UTC clock at receipt is used for everything (`received_at`, pricing, the age check). `sent_at` is used only for the age check (older than 300 s → 422 `stale`) and the clock check (more than 120 s ahead → 422 `clock`).\n\n### Authentication failures\nA missing, malformed or unknown key, a non-bot account or an inactive (paused) account all get `401 {\"detail\": \"...\"}`. Note this is FastAPI's `detail` shape, **not** the `status`/`code`/`reason` shape used by every other refusal.",
    "contact": {"name": "GEAC Systems", "url": "https://geacsystems.com/contact"},
    "x-last-updated": "2026-10-30",
    "x-changelog": [
      {
        "version": "1.1.0",
        "date": "2026-10-30",
        "changes": [
          "Ideas no longer carry a horizon: `horizon_days` is ignored if sent (an `amend` must now carry `conviction`). An idea stays open until it is closed or until the review checkpoint (120 trading sessions) closes it as `expiry`.",
          "Minimum hold of 15 minutes after the start of the entry bar; `earliest_close` is returned on every accepted `new`.",
          "Entries are fixed to a five-minute bar at receipt (next 5-minute boundary during the regular session, otherwise the next session's 09:30 bar).",
          "Universe widened from the Nasdaq-100 to NYSE/Nasdaq-listed stocks (any domicile, excluding foreign ADRs) with market cap ≥ $2bn and dollar ADV ≥ $20m plus every S&P 500 and Nasdaq-100 member; a name outside it is refused with the new code `universe`.",
          "Same-day re-entry after a close is allowed (ban removed 29 October 2026)."
        ]
      },
      {
        "version": "1.0.0",
        "date": "2026-10",
        "changes": [
          "First bot API: Nasdaq-100 universe, `horizon_days` on new ideas, `client_ref` idempotency, `sent_at` freshness check, 60/min and 500/hour rate limits."
        ]
      }
    ],
    "x-proposed": {
      "status": "NOT IMPLEMENTED — proposals only. Nothing in this list exists on the server today; a bot must recover state from the duplicate reply and the owner's web dashboard.",
      "endpoints": [
        {"method": "GET", "path": "/v1/ideas", "purpose": "List this bot's open and pending ideas."},
        {"method": "GET", "path": "/v1/ideas/{idea_id}", "purpose": "Fetch one idea, including its priced entry and final value when closed."},
        {"method": "GET", "path": "/v1/messages/{client_ref}", "purpose": "Look up the recorded answer for a client_ref."},
        {"method": "GET", "path": "/v1/universe", "purpose": "The eligible symbol list."},
        {"method": "GET", "path": "/v1/calendar", "purpose": "Trading days, holidays and early closes."}
      ]
    }
  },
  "servers": [
    {"url": "https://geacsystems.com", "description": "Production. There is no test environment: every accepted message is a real idea."}
  ],
  "security": [{"bearerKey": []}],
  "tags": [
    {"name": "bot", "description": "The machine door: one key per bot account, one order per message."}
  ],
  "paths": {
    "/v1/ping": {
      "get": {
        "tags": ["bot"],
        "operationId": "ping",
        "summary": "Check the key and read the bot's limits",
        "description": "Confirms the API key works and returns the account's limits, today's counts, the number of open ideas and the server's clock. **No side effects**: a ping is not recorded, does not count as activity and is not rate limited. Compare `server_time` with your own clock before sending ideas (`sent_at` must be within 300 s behind / 120 s ahead of it).",
        "security": [{"bearerKey": []}],
        "responses": {
          "200": {
            "description": "The key is valid.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Ping"},
                "examples": {
                  "ping": {
                    "summary": "Authenticated ping",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown API key, or the account is not a bot or is inactive. The body is FastAPI's `{\"detail\": ...}` shape, not the `status`/`code`/`reason` shape.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Unauthorized"},
                "examples": {
                  "ping_unauthorized": {
                    "summary": "Ping with a missing or unknown key",
                    "value": {"detail": "missing or unknown API key; send it as 'Authorization: Bearer geac_...'"}
                  }
                }
              }
            }
          },
          "500": {"$ref": "#/components/responses/ServerFault"}
        }
      }
    },
    "/v1/ideas": {
      "post": {
        "tags": ["bot"],
        "operationId": "postIdea",
        "summary": "Send one order: new, amend or close",
        "description": "One message, one order. The body is a single JSON object whose `event` selects the shape: `NewIdea`, `AmendIdea` or `CloseIdea`. Unknown fields are ignored.\n\n**Processing order** (the first failing step answers):\n1. Authentication → 401.\n2. Rate limit → 429 (`Retry-After` header; not recorded).\n3. Body larger than 65,536 bytes → 413 `too_large` (not recorded).\n4. Body not a single JSON object → 400 `bad_json` (not recorded).\n5. `event` missing or not `new|amend|close` (case-insensitive) → 400 (not recorded).\n6. `client_ref` missing or not 1–64 characters after trimming → 400 (not recorded).\n7. **Duplicate check** on (bot, `client_ref`): an earlier accepted message → 200 `duplicate`; an earlier refused message → its original status with code `repeat_of_refused`. The body of the repeat is ignored.\n8. `sent_at` parsed (ISO 8601 with timezone; `Z` accepted) → 400 `bad_field` if unparsable; older than 300 s → 422 `stale`; more than 120 s ahead → 422 `clock`. Both recorded.\n9. Permission log entry (`bot.message`). A refusal here would be 403 `not_allowed`; not reachable for a valid bot today.\n10. Event handling (see the schemas). Intake rule breaches → 422 `rule`; other refusals carry their own code.\n11. The message is recorded against the `client_ref` with its status, HTTP status, reason, idea id and the first 4,000 bytes of the body.\n\n**Side effects of an accepted message**: `new` writes a ledger `create` event, an open `idea_state` row, a pending `entries` row and an attestation, and emails the owner. `amend` writes a ledger event and updates conviction (the review date does not move; the idea is not re-priced). `close` writes a ledger `close` event, sets the idea closed with `closed_at` = the UTC date of acceptance, marks the entry closed, and emails the owner.\n\n**Timestamps**: `received_at` is the server's UTC receipt time and is the time the idea is sealed. `earliest_close` is the start of the entry bar plus 15 minutes (for an idea received at 17:00 New York this is 09:45 New York the next trading day). `review_date` is receipt + 174 calendar days (about 120 trading sessions); a reset to the exact 120th session exists in the code but does not take effect in practice, so treat the date as final unless the idea is reconfirmed. `closed_at` on a close is the acceptance time (the ledger event timestamp); the idea is valued at the official close of that **UTC** date, so a close accepted after 20:00 New York is valued at the next trading day's close.",
        "security": [{"bearerKey": []}],
        "requestBody": {
          "required": true,
          "description": "A single JSON object. `event` selects the shape. The server reads the body as raw bytes: a malformed body is answered 400 `bad_json`, never a framework validation error.",
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/IdeaMessage"},
              "examples": {
                "new_long": {"summary": "Open a long (BUY) idea", "value": {"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}},
                "new_short": {"summary": "Open a short (SELL) idea with a market hedge", "value": {"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"}},
                "amend": {"summary": "Amend conviction", "value": {"event": "amend", "client_ref": "bot1-2026-11-03-0003", "sent_at": "2026-11-03T15:05:12Z", "idea_id": "i_1a2b3c4d5e6f", "conviction": 4}},
                "close": {"summary": "Close the long idea", "value": {"event": "close", "client_ref": "bot1-2026-11-03-0004", "sent_at": "2026-11-03T19:40:02Z", "idea_id": "i_1a2b3c4d5e6f", "reason": "thesis_realised"}},
                "reversal_new": {"summary": "Reversal, step 2: open the opposite side after the close was accepted", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0005", "sent_at": "2026-11-03T19:40:03Z", "symbol": "MSFT", "side": "sell", "conviction": 2, "hedge": "sector"}},
                "duplicate": {"summary": "Repeat of an accepted reference", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0001", "sent_at": "2026-11-03T14:31:05Z", "symbol": "MSFT", "side": "buy", "conviction": 3, "hedge": "sector"}},
                "repeat_of_refused": {"summary": "Repeat of a refused reference", "value": {"event": "close", "client_ref": "bot1-2026-11-03-0006", "sent_at": "2026-11-03T14:46:00Z", "idea_id": "i_7f8e9d0c1b2a", "reason": "price"}},
                "refused_min_hold": {"summary": "Close refused: minimum holding period", "value": {"event": "close", "client_ref": "bot1-2026-11-03-0006", "sent_at": "2026-11-03T14:45:30Z", "idea_id": "i_7f8e9d0c1b2a", "reason": "price"}},
                "refused_stale": {"summary": "Refused: stale signal", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0007", "sent_at": "2026-11-03T14:20:00Z", "symbol": "AAPL", "side": "buy", "conviction": 2, "hedge": "sector"}},
                "refused_clock": {"summary": "Refused: clock ahead of the server", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0008", "sent_at": "2026-11-03T14:40:00Z", "symbol": "AAPL", "side": "buy", "conviction": 2, "hedge": "sector"}},
                "refused_universe": {"summary": "Refused: name not eligible", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0009", "sent_at": "2026-11-03T14:41:00Z", "symbol": "TINY", "side": "buy", "conviction": 2, "hedge": "sector"}},
                "refused_rule_open": {"summary": "Refused: an idea in the name is already open", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0010", "sent_at": "2026-11-03T14:42:00Z", "symbol": "TSLA", "side": "buy", "conviction": 2, "hedge": "sector"}},
                "refused_not_open": {"summary": "Refused: nothing to close", "value": {"event": "close", "client_ref": "bot1-2026-11-03-0011", "sent_at": "2026-11-03T19:41:00Z", "symbol": "NVDA", "reason": "price"}},
                "refused_missing_field": {"summary": "Refused: a required field is missing", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0012", "sent_at": "2026-11-03T14:43:00Z", "symbol": "AAPL", "side": "buy", "conviction": 2}},
                "rate_limited": {"summary": "Rate limited", "value": {"event": "new", "client_ref": "bot1-2026-11-03-0013", "sent_at": "2026-11-03T14:44:00Z", "symbol": "AAPL", "side": "buy", "conviction": 2, "hedge": "sector"}}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted (`status: accepted`, shape by `event`), or a repeat of an already-accepted `client_ref` (`status: duplicate`, a short object that does **not** reproduce the original response).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {"$ref": "#/components/schemas/AcceptedNew"},
                    {"$ref": "#/components/schemas/AcceptedAmend"},
                    {"$ref": "#/components/schemas/AcceptedClose"},
                    {"$ref": "#/components/schemas/Duplicate"}
                  ]
                },
                "examples": {
                  "new_long": {"summary": "Open a long (BUY) idea", "value": {"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"}},
                  "new_short": {"summary": "Open a short (SELL) idea with a market hedge", "value": {"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"}},
                  "amend": {"summary": "Amend conviction", "value": {"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"}},
                  "close": {"summary": "Close the long idea", "value": {"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"}},
                  "reversal_new": {"summary": "Reversal, step 2: open the opposite side after the close was accepted", "value": {"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"}},
                  "duplicate": {"summary": "Repeat of an accepted reference", "value": {"status": "duplicate", "idea_id": "i_1a2b3c4d5e6f", "client_ref": "bot1-2026-11-03-0001", "first_received_at": "2026-11-03T14:31:05.412+00:00"}}
                }
              }
            }
          },
          "400": {
            "description": "Malformed request: `bad_json` (body is not a single JSON object; not recorded), `missing_field` or `bad_field` (a required field is absent or has the wrong shape, length or value). Field errors on `event` or `client_ref` are not recorded (`client_ref` is then `null` or absent); field errors inside `new`/`amend`/`close` **are** recorded, so a repeat of the same reference returns 400 `repeat_of_refused`.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Refused400"},
                "examples": {
                  "refused_missing_field": {"summary": "Refused: a required field is missing", "value": {"status": "refused", "code": "missing_field", "client_ref": "bot1-2026-11-03-0012", "reason": "'hedge' is required"}},
                  "bad_json": {"summary": "Refused: body is not a JSON object", "value": {"status": "refused", "code": "bad_json", "reason": "the body must be a single JSON object"}}
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown API key, or the account is not a bot or is inactive (paused). Body is `{\"detail\": ...}`, not the `status`/`code`/`reason` shape. Not recorded.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Unauthorized"},
                "examples": {
                  "unauthorized": {"summary": "Missing or unknown key", "value": {"detail": "missing or unknown API key; send it as 'Authorization: Bearer geac_...'"}}
                }
              }
            }
          },
          "403": {
            "description": "Refused by the permissions engine (`not_allowed`). The code path exists but is not reachable for a valid, active bot today. Recorded, so a repeat would return 403 `repeat_of_refused`.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Refused403"}
              }
            }
          },
          "413": {
            "description": "Body larger than 65,536 bytes (`too_large`). Not recorded.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Refused413"},
                "examples": {
                  "too_large": {"summary": "Body over 64 KB", "value": {"status": "refused", "code": "too_large", "reason": "message larger than 64 KB"}}
                }
              }
            }
          },
          "422": {
            "description": "Rule, timing or state refusal. Codes: `stale` (sent_at older than 300 s), `clock` (sent_at more than 120 s ahead), `unknown_idea` (idea_id does not belong to this bot), `not_open` (idea already closed, or no open idea in the symbol), `side_mismatch` (side disagrees with the open idea), `universe` (name not eligible or has left; `close` is still accepted), `rule` (an intake rule: already an open idea in the name, daily limit, open cap, custom hedge not eligible or equal to the idea, thesis under 10 words, target/stop out of range, nothing changed on amend, minimum hold not yet reached on close), `repeat_of_refused` (the reference was refused before; the original reason is returned). **All are recorded**, including the minimum-hold refusal: a later close needs a new `client_ref`.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Refused422"},
                "examples": {
                  "repeat_of_refused": {"summary": "Repeat of a refused reference", "value": {"status": "refused", "code": "repeat_of_refused", "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"}},
                  "refused_min_hold": {"summary": "Close refused: minimum holding period", "value": {"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"}},
                  "refused_stale": {"summary": "Refused: stale signal", "value": {"status": "refused", "code": "stale", "client_ref": "bot1-2026-11-03-0007", "reason": "'sent_at' is 661 seconds old; signals older than 300 seconds are refused"}},
                  "refused_clock": {"summary": "Refused: clock ahead of the server", "value": {"status": "refused", "code": "clock", "client_ref": "bot1-2026-11-03-0008", "reason": "'sent_at' is 535 seconds in the future; check the bot's clock"}},
                  "refused_universe": {"summary": "Refused: name not eligible", "value": {"status": "refused", "code": "universe", "client_ref": "bot1-2026-11-03-0009", "reason": "TINY is not in the GEAC universe (US-listed stocks (NYSE or Nasdaq, any domicile, excluding ADRs of foreign companies) with a market value above $100m and more than $1m traded a day, plus every S&P 500 and Nasdaq-100 member)"}},
                  "refused_rule_open": {"summary": "Refused: an idea in the name is already open", "value": {"status": "refused", "code": "rule", "client_ref": "bot1-2026-11-03-0010", "reason": "you already have an open idea in TSLA; change or close it instead"}},
                  "refused_not_open": {"summary": "Refused: nothing to close", "value": {"status": "refused", "code": "not_open", "client_ref": "bot1-2026-11-03-0011", "reason": "this bot has no open idea in NVDA"}}
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 60 requests in the last 60 s or 500 in the last 3600 s for this bot. Wait `Retry-After` seconds and resend the **same** message and reference (the call was not recorded); if `sent_at` would then be older than 300 s, re-decide and use a new reference.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before the next request.",
                "required": true,
                "schema": {"type": "string", "pattern": "^[0-9]+$"},
                "example": "17"
              }
            },
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Refused429"},
                "examples": {
                  "rate_limited": {"summary": "Rate limited", "value": {"status": "refused", "code": "rate_limited", "reason": "too many requests; retry in 17 seconds"}}
                }
              }
            }
          },
          "500": {"$ref": "#/components/responses/ServerFault"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "`Authorization: Bearer geac_...`. Keys are 48 characters: the prefix `geac_` followed by 43 URL-safe characters (`A–Z a–z 0–9 - _`). The owner creates a key in the web app (Settings → Bot Connection); it is shown once and stored as a SHA-256 hash. Creating a new key **replaces** the old one immediately; there is no separate revoke call. Only accounts with `input_mode='bot'` can hold a key."
      }
    },
    "responses": {
      "ServerFault": {
        "description": "Server fault. Starlette's default handler answers with the plain text `Internal Server Error`; there is no JSON contract for this status. Nothing was recorded against the `client_ref` unless a later repeat of it says otherwise.",
        "content": {
          "text/plain": {
            "schema": {"type": "string"},
            "example": "Internal Server Error"
          }
        }
      }
    },
    "schemas": {
      "ClientRef": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64,
        "description": "The bot's own reference for this message, unique per bot. Trimmed of surrounding whitespace before the length check. Looked up before anything else is validated; kept indefinitely.",
        "examples": ["bot1-2026-11-03-0001"]
      },
      "SentAt": {
        "type": "string",
        "format": "date-time",
        "maxLength": 40,
        "description": "When the bot decided, ISO 8601 **with a timezone** (`Z` accepted). Refused 400 `bad_field` without a timezone; 422 `stale` if more than 300 s before the server's receipt time; 422 `clock` if more than 120 s after it. Used only for these checks, never for pricing.",
        "examples": ["2026-11-03T14:31:05Z"]
      },
      "Symbol": {
        "type": "string",
        "minLength": 1,
        "maxLength": 12,
        "description": "Ticker as used by FMP; upper-cased by the server. Share classes use a hyphen (`BRK-B`, `BF-B`). There is no public list of eligible symbols; an ineligible name is refused 422 `universe`.",
        "examples": ["MSFT", "BRK-B"]
      },
      "Side": {
        "type": "string",
        "pattern": "^([Bb][Uu][Yy]|[Ss][Ee][Ll][Ll])$",
        "description": "`buy` or `sell`, any letter case (the server upper-cases). Responses always return `BUY` or `SELL`.",
        "examples": ["buy", "sell"]
      },
      "Conviction": {
        "type": "integer",
        "minimum": 1,
        "maximum": 4,
        "description": "1 = Low, 2 = Medium, 3 = High, 4 = Max. Sets the platform's notional size ($1.3m / $2.65m / $4m / $6m, for a stock of typical volatility, scaled down for a more volatile stock and up for a steadier one, capped at 10% of the name's dollar ADV). Net P&L in US dollars on that size is what contributors are ranked and paid on. The server also accepts a numeric string such as `\"3\"`; send an integer."
      },
      "Hedge": {
        "type": "string",
        "minLength": 1,
        "maxLength": 12,
        "description": "`sector` (the name's S&P 500 GICS sector index), `market` (S&P 500), or a ticker for a dollar-neutral single-name hedge. `sector`/`market` are matched case-insensitively; anything else is treated as a ticker (upper-cased) and must be in the universe and not the idea itself (otherwise 422 `rule`).",
        "examples": ["sector", "market", "NVDA"]
      },
      "Style": {
        "type": "string",
        "enum": ["catalyst", "earnings", "valuation", "technical", "macro", "research", "news", "other"],
        "description": "Lower-cased by the server before the check (so `Technical` is accepted). An unknown style is refused 422 `rule`."
      },
      "Styles": {
        "description": "Optional. Either a list of style words or one comma-separated string. Each must be one of the `Style` values (case-insensitive).",
        "oneOf": [
          {"type": "array", "items": {"$ref": "#/components/schemas/Style"}},
          {"type": "string", "description": "Comma-separated styles, e.g. `technical,news`.", "examples": ["valuation", "technical,news"]}
        ]
      },
      "Thesis": {
        "type": "string",
        "maxLength": 2000,
        "description": "Optional free text. Longer than 2000 characters → 400 `bad_field`. If given it must be at least 10 words, otherwise 422 `rule`. An empty string is treated as absent."
      },
      "Pct": {
        "type": "number",
        "minimum": -300,
        "maximum": 300,
        "description": "Optional percentage. If given, 0 < |value| ≤ 300 (zero is refused 422 `rule`; the sign is not interpreted). Stored and shown only: **no server-side action** (no stop execution, no alerts). The server also accepts a numeric string; send a number."
      },
      "HorizonDays": {
        "type": "integer",
        "deprecated": true,
        "description": "**Deprecated and ignored** since 29 October 2026. Ideas no longer carry a horizon; the field is accepted for older bots and has no effect."
      },
      "IdeaIdRef": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40,
        "description": "An idea id returned by an accepted `new` (`i_` + 12 hex characters). It must belong to this bot (otherwise 422 `unknown_idea`) and be open (otherwise 422 `not_open`).",
        "examples": ["i_1a2b3c4d5e6f"]
      },
      "IdeaId": {
        "type": "string",
        "pattern": "^i_[0-9a-f]{12}$",
        "description": "GEAC's idea id: `i_` followed by 12 lowercase hex characters.",
        "examples": ["i_1a2b3c4d5e6f"]
      },
      "CloseReason": {
        "type": "string",
        "enum": ["thesis_realised", "thesis_wrong", "price", "expiry", "compliance"],
        "description": "Why the idea is closed. Lower-cased by the server; anything else is refused 400 `bad_field`."
      },
      "IdeaMessage": {
        "description": "One order. `event` (case-insensitive on the server; send lowercase) selects the shape.",
        "oneOf": [
          {"$ref": "#/components/schemas/NewIdea"},
          {"$ref": "#/components/schemas/AmendIdea"},
          {"$ref": "#/components/schemas/CloseIdea"}
        ],
        "discriminator": {
          "propertyName": "event",
          "mapping": {
            "new": "#/components/schemas/NewIdea",
            "amend": "#/components/schemas/AmendIdea",
            "close": "#/components/schemas/CloseIdea"
          }
        }
      },
      "NewIdea": {
        "type": "object",
        "title": "NewIdea",
        "description": "Open an idea. Checks, in order: universe (422 `universe`), then intake: custom hedge in the universe and not the idea itself, account active, no open idea already in the name for this bot, daily limit (50 new ideas per UTC day by default; the operator may set 1–200), open cap (100 open ideas) — all 422 `rule`. Opening a SELL does not close a BUY: one open idea per name per bot, so a `new` on the other side while one is open is refused. Unknown fields are ignored.",
        "required": ["event", "client_ref", "sent_at", "symbol", "side", "conviction", "hedge"],
        "properties": {
          "event": {"type": "string", "enum": ["new"]},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "sent_at": {"$ref": "#/components/schemas/SentAt"},
          "symbol": {"$ref": "#/components/schemas/Symbol"},
          "side": {"$ref": "#/components/schemas/Side"},
          "conviction": {"$ref": "#/components/schemas/Conviction"},
          "hedge": {"$ref": "#/components/schemas/Hedge"},
          "styles": {"$ref": "#/components/schemas/Styles"},
          "thesis": {"$ref": "#/components/schemas/Thesis"},
          "target_pct": {"$ref": "#/components/schemas/Pct"},
          "stop_pct": {"$ref": "#/components/schemas/Pct"},
          "horizon_days": {"$ref": "#/components/schemas/HorizonDays"}
        }
      },
      "AmendIdea": {
        "type": "object",
        "title": "AmendIdea",
        "description": "Change the conviction of an open idea. Identify it by `idea_id`, or by `symbol` (plus optional `side`; 422 `side_mismatch` if it disagrees). Neither → 400 `missing_field`. `conviction` is required (400 `missing_field`). The name must still be in the universe (422 `universe`). Only conviction can change through the API (thesis, target and stop only in the web app); the same value → 422 `rule` \"nothing changed\". Amending does **not** move the review date and does not re-price the idea.",
        "required": ["event", "client_ref", "sent_at", "conviction"],
        "anyOf": [
          {"required": ["idea_id"]},
          {"required": ["symbol"]}
        ],
        "properties": {
          "event": {"type": "string", "enum": ["amend"]},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "sent_at": {"$ref": "#/components/schemas/SentAt"},
          "idea_id": {"$ref": "#/components/schemas/IdeaIdRef"},
          "symbol": {"$ref": "#/components/schemas/Symbol"},
          "side": {"$ref": "#/components/schemas/Side"},
          "conviction": {"$ref": "#/components/schemas/Conviction"},
          "horizon_days": {"$ref": "#/components/schemas/HorizonDays"}
        }
      },
      "CloseIdea": {
        "type": "object",
        "title": "CloseIdea",
        "description": "Close an open idea. Identify it as for `amend`; the idea is resolved **before** `reason` is checked, so an unknown or closed idea answers 422 even when `reason` is also bad. `reason` is required and must be one of the `CloseReason` values (400 `bad_field` otherwise). **Minimum hold**: refused 422 `rule` if the server time is before `earliest_close` — and that refusal is recorded against the `client_ref`, so the later close needs a new reference. A close is accepted whether or not the entry has been priced yet; the entry is still priced when its bar closes, so a same-day round trip is valued. A `close` is accepted for a name that has left the universe. Re-entry in the same name and side is allowed immediately after the close is accepted.",
        "required": ["event", "client_ref", "sent_at", "reason"],
        "anyOf": [
          {"required": ["idea_id"]},
          {"required": ["symbol"]}
        ],
        "properties": {
          "event": {"type": "string", "enum": ["close"]},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "sent_at": {"$ref": "#/components/schemas/SentAt"},
          "idea_id": {"$ref": "#/components/schemas/IdeaIdRef"},
          "symbol": {"$ref": "#/components/schemas/Symbol"},
          "side": {"$ref": "#/components/schemas/Side"},
          "reason": {"$ref": "#/components/schemas/CloseReason"}
        }
      },
      "AcceptedNew": {
        "type": "object",
        "title": "AcceptedNew",
        "description": "A `new` was accepted and sealed at `received_at`.",
        "required": ["status", "event", "idea_id", "client_ref", "symbol", "side", "received_at", "review_date", "pricing", "minimum_hold", "earliest_close"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["accepted"]},
          "event": {"type": "string", "enum": ["new"]},
          "idea_id": {"$ref": "#/components/schemas/IdeaId"},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "symbol": {"type": "string", "description": "Upper-cased symbol."},
          "side": {"type": "string", "enum": ["BUY", "SELL"]},
          "received_at": {"type": "string", "format": "date-time", "description": "Server UTC receipt time, millisecond precision with a `+00:00` offset. This is the time the idea is sealed."},
          "review_date": {"type": "string", "format": "date", "description": "Receipt + 174 calendar days (about 120 trading sessions). A reset to the exact 120th session exists in the code but does not take effect in practice; treat the date as final. The nightly closes the idea with reason `expiry` on that date unless a person reconfirms it in the web app (no API event for that)."},
          "pricing": {"type": "string", "enum": ["next 5-minute VWAP after receipt"], "description": "Returned literally as `next 5-minute VWAP after receipt`. The bar is the next five-minute boundary after receipt during the regular session (09:30–15:55 New York), otherwise the next session's 09:30 bar. Since 30 Oct 2026 the entry is priced about 90 seconds after the bar closes at the volume-weighted average of the bar's one-minute bars (fallback: the bar's typical price when the vendor publishes no minutes), with the hedge leg priced at the same bar."},
          "minimum_hold": {"type": "string", "enum": ["15 minutes"], "description": "The idea cannot be closed by the bot before `earliest_close`."},
          "earliest_close": {"type": "string", "format": "date-time", "description": "UTC, second precision: start of the entry bar + 15 minutes. For an idea received at 17:00 New York this is 09:45 New York the next trading day. A close before it is refused 422 `rule` and that refusal is recorded against its `client_ref`."}
        }
      },
      "AcceptedAmend": {
        "type": "object",
        "title": "AcceptedAmend",
        "description": "An `amend` was accepted. The review date is unchanged.",
        "required": ["status", "event", "idea_id", "client_ref", "symbol", "side", "conviction", "review_date"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["accepted"]},
          "event": {"type": "string", "enum": ["amend"]},
          "idea_id": {"$ref": "#/components/schemas/IdeaId"},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "symbol": {"type": "string"},
          "side": {"type": "string", "enum": ["BUY", "SELL"]},
          "conviction": {"type": "integer", "minimum": 1, "maximum": 4, "description": "The new conviction."},
          "review_date": {"type": "string", "format": "date", "description": "The idea's current review date (not moved by an amend; provisional until the entry is priced)."}
        }
      },
      "AcceptedClose": {
        "type": "object",
        "title": "AcceptedClose",
        "description": "A `close` was accepted. The idea is valued at the official close (16:00 New York) of the **UTC date** of `closed_at` by the nightly job; a close accepted after 20:00 New York carries the next calendar day's date and is valued at the next trading day's close.",
        "required": ["status", "event", "idea_id", "client_ref", "symbol", "side", "closed_at", "reason"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["accepted"]},
          "event": {"type": "string", "enum": ["close"]},
          "idea_id": {"$ref": "#/components/schemas/IdeaId"},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "symbol": {"type": "string"},
          "side": {"type": "string", "enum": ["BUY", "SELL"]},
          "closed_at": {"type": "string", "format": "date-time", "description": "The acceptance time (the ledger `close` event timestamp), UTC with millisecond precision. Not a market price time."},
          "reason": {"$ref": "#/components/schemas/CloseReason"}
        }
      },
      "Duplicate": {
        "type": "object",
        "title": "Duplicate",
        "description": "The `client_ref` was already accepted. Nothing new was created and the body of this repeat was ignored. Only the idea id and the time of first receipt come back; `earliest_close` and `review_date` are **not** repeated.",
        "required": ["status", "idea_id", "client_ref", "first_received_at"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["duplicate"]},
          "idea_id": {"$ref": "#/components/schemas/IdeaId"},
          "client_ref": {"$ref": "#/components/schemas/ClientRef"},
          "first_received_at": {"type": "string", "format": "date-time", "description": "Server UTC receipt time of the first message with this reference (equals that message's `received_at`)."}
        }
      },
      "Refused": {
        "type": "object",
        "title": "Refused",
        "description": "Every refusal other than 401 and 500. `client_ref` echoes the reference when it was read: it is absent for `bad_json`, `too_large` and `rate_limited`, and `null` when the refusal is about `event` or `client_ref` itself.",
        "required": ["status", "code", "reason"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["refused"]},
          "code": {
            "type": "string",
            "enum": ["bad_json", "missing_field", "bad_field", "not_allowed", "too_large", "stale", "clock", "unknown_idea", "not_open", "side_mismatch", "universe", "rule", "repeat_of_refused", "rate_limited"]
          },
          "reason": {"type": "string", "description": "Plain-English explanation. For `repeat_of_refused` it is the **original** refusal's reason."},
          "client_ref": {"type": ["string", "null"], "maxLength": 64}
        }
      },
      "Refused400": {
        "title": "Refused400",
        "description": "400 body. `repeat_of_refused` appears here when the original refusal of the reference was a recorded 400 (a field error inside `new`/`amend`/`close`).",
        "allOf": [
          {"$ref": "#/components/schemas/Refused"},
          {"properties": {"code": {"enum": ["bad_json", "missing_field", "bad_field", "repeat_of_refused"]}}}
        ]
      },
      "Refused403": {
        "title": "Refused403",
        "description": "403 body. Not reachable for a valid, active bot today.",
        "allOf": [
          {"$ref": "#/components/schemas/Refused"},
          {"properties": {"code": {"enum": ["not_allowed", "repeat_of_refused"]}}}
        ]
      },
      "Refused413": {
        "title": "Refused413",
        "allOf": [
          {"$ref": "#/components/schemas/Refused"},
          {"properties": {"code": {"enum": ["too_large"]}}}
        ]
      },
      "Refused422": {
        "title": "Refused422",
        "allOf": [
          {"$ref": "#/components/schemas/Refused"},
          {"properties": {"code": {"enum": ["stale", "clock", "unknown_idea", "not_open", "side_mismatch", "universe", "rule", "repeat_of_refused"]}}}
        ]
      },
      "Refused429": {
        "title": "Refused429",
        "allOf": [
          {"$ref": "#/components/schemas/Refused"},
          {"properties": {"code": {"enum": ["rate_limited"]}}}
        ]
      },
      "Unauthorized": {
        "type": "object",
        "title": "Unauthorized",
        "description": "FastAPI's `HTTPException` body. The only response in this API with this shape.",
        "required": ["detail"],
        "additionalProperties": false,
        "properties": {
          "detail": {"type": "string", "enum": ["missing or unknown API key; send it as 'Authorization: Bearer geac_...'"]}
        }
      },
      "Ping": {
        "type": "object",
        "title": "Ping",
        "required": ["status", "bot", "owner", "cohort", "limits", "today", "open_ideas", "server_time"],
        "additionalProperties": false,
        "properties": {
          "status": {"type": "string", "enum": ["ok"]},
          "bot": {"type": ["string", "null"], "description": "The bot's name as given in the application (null if none was set)."},
          "owner": {"type": "string", "description": "The owner's name."},
          "cohort": {"type": "string", "enum": ["provisional", "established"], "description": "Provisional for three calendar months from joining (ideas are priced and ranked but earn nothing), then established."},
          "limits": {
            "type": "object",
            "required": ["ideas_per_day", "open_ideas", "requests_per_minute", "requests_per_hour", "max_signal_age_s", "minimum_hold_minutes", "review_sessions"],
            "additionalProperties": false,
            "properties": {
              "ideas_per_day": {"type": "integer", "minimum": 1, "maximum": 200, "description": "New ideas per UTC calendar day (default 50; the operator may set 1–200)."},
              "open_ideas": {"type": "integer", "description": "Open ideas at once per bot (100)."},
              "requests_per_minute": {"type": "integer", "description": "Rolling 60 s (60)."},
              "requests_per_hour": {"type": "integer", "description": "Rolling 3600 s (500)."},
              "max_signal_age_s": {"type": "integer", "description": "Oldest accepted `sent_at` in seconds (300)."},
              "minimum_hold_minutes": {"type": "integer", "description": "Minimum hold after the start of the entry bar (15)."},
              "review_sessions": {"type": "integer", "description": "Trading sessions until the review checkpoint (120)."}
            }
          },
          "today": {
            "type": "object",
            "required": ["new_ideas", "messages"],
            "additionalProperties": false,
            "properties": {
              "new_ideas": {"type": "integer", "minimum": 0, "description": "Ideas created today (UTC date)."},
              "messages": {"type": "integer", "minimum": 0, "description": "Recorded `/v1/ideas` messages received today (UTC). **Always 0 on a ping**: the ping reads the message list with a limit of 0, so this counter is not populated here (the owner's web dashboard shows the real count)."}
            }
          },
          "open_ideas": {"type": "integer", "minimum": 0},
          "server_time": {"type": "string", "format": "date-time", "description": "Server UTC time, second precision, `+00:00` offset. Compare with your own clock."}
        }
      }
    }
  }
}
