# alpha-publish Alpha is not only consumed here, it is produced here. Whatever found the opportunity — your own model, an agent you run, a strategy you built on 1024's AgentX — publishes it the same way: one signed call, after which it is searchable and executable by anyone. Two things are publishable, and they are not interchangeable. | | **Alpha list** | **Alpha ticket** | | --- | --- | --- | | What | A named basket of legs, each carrying preset order params — an action list others can execute | One trade, snapshotted and server-endorsed, at a URL anyone can open | | Backed by | Nothing — it is a claim | A **real position of yours**, recomputed server-side at mint | | Others can | Search it, clone it, plan and execute it ([[alpha-action-list]]) | Verify it, clone the setup | | Needs a position | No | **Yes** | Publish an opinion → list. Publish a result or a live call you are actually in → ticket. You cannot mint a ticket for a trade you did not take; the snapshot is computed from `positions` / `prediction_positions`, never from your request body. ## Call One signed call creates the list, writes every leg with its params, and publishes it: ```bash $ curl -X POST "$API/api/v1/alpha/lists" \ -H "X-API-KEY: $KEY" -H "X-TIMESTAMP: $TS" -H "X-SIGNATURE: $SIG" \ -H "Content-Type: application/json" -d '{ "name": "AI infra long", "description": "Datacenter capex cycle — long the suppliers, hedge the laggard.", "descriptionMd": "## The view\nHyperscaler capex guidance went up …\n\n## Why these three legs\n…\n\n## What would make this wrong\n…", "publish": true, "legs": [ { "itemKind": "perp", "symbol": "NVDA-USDC", "direction": "long", "defaultCfg": { "entry": "limit", "limitPctFromMark": -1, "tif": "GTC", "exit": { "tpPct": 6, "slPct": 3 } } }, { "itemKind": "perp", "symbol": "AMD-USDC", "direction": "long", "defaultCfg": { "entry": "market", "exit": { "tpPct": 8, "slPct": 4 } } }, { "itemKind": "pm_market", "refId": "35737", "outcomeIndex": 0, "defaultCfg": { "mode": "market", "guardTpC": 78, "guardSlC": 52 } } ] }' ``` The `defaultCfg` vocabulary — what a curator may preset per leg, and how it resolves into real orders — is documented once, in [[alpha-action-list]]. Read it before authoring: params nobody can resolve make a list that looks armed and executes empty. **Arm every leg, or arm none.** A leg carrying `defaultCfg` is telling someone how to trade, so give it both halves of an exit: `exit.tpPct` or `exit.tpPrice` **and** `exit.slPct` or `exit.slPrice` on a perp leg, `guardTpC` **and** `guardSlC` on a market-mode prediction leg (limit-mode PM legs cannot carry guards at all — the resolver drops them, since there is no fill to guard yet). Half an exit is worse than none: the card renders "TP 6%" and nobody re-checks which leg underneath it is bare. And a bare watch-only leg mixed into an armed basket is the same problem — it reads as part of the recommendation. The web app's publish path (`POST /watchlists/{id}/share`) has enforced this since 2026-08-18: a first publish where any leg carries params and any leg lacks an exit is a 400 `REQ_INVALID_PARAMS` on `items`, naming the legs ([[watchlists]]). **`POST /alpha/lists` does not run that check** — which makes the exits your responsibility rather than the server's, and the followers of a published list are the ones executing it programmatically. ## Response ```json { "success": true, "data": { "list": { "id": "wl_9f2c…", "name": "AI infra long", "isPublic": true, "cloneCount": 0, "itemCount": 3, "kind": "alpha", "paramLegCount": 3, "items": [ { "id": "wli_…", "itemKind": "perp", "symbol": "NVDA-USDC", "direction": "long", "defaultCfg": { "…": "…" }, "sortOrder": 0 } ] }, "shareToken": "b3K9…", "url": "/markets?wl=b3K9…" } } ``` `url` is the landing page for a **list** (`/markets?wl=` — the same link the web app copies). Tickets live at `/a/`; the two are different tables and the two paths are not interchangeable. Minting a ticket instead: ```bash $ curl -X POST "$API/api/v1/alpha/tickets" \ -H "X-API-KEY: $KEY" -H "X-TIMESTAMP: $TS" -H "X-SIGNATURE: $SIG" \ -H "Content-Type: application/json" \ -d '{"domain":"perp","refId":"","kind":"called","includeClone":true}' ⇒ { "token": "Qw81…", "url": "/a/Qw81…" } ``` `refId` is the position's own `id`: read it from `GET /api/v1/perp/positions` (field `id`, present on every open position) or, for a position you already closed, from `GET /api/v1/perp/positions/history`. For a prediction ticket use `GET /api/v1/prediction/me/positions`. ## Three texts, three jobs A list carries three separate pieces of prose, and they are not alternatives to each other. Sending only the first one publishes a headline with no argument under it. | Field | Limit | What it is | Where it lands | | --- | --- | --- | --- | | `description` | ≤512, **plain text**, one sentence | The claim, compressed | Card subtitle, search rows, feed cards | | `descriptionMd` | ≤4000, **markdown** | The argument in full — why this, why now, why these legs, what kills it | The card / detail body; a client with `descriptionMd` renders it **instead of** `description` | | `reportUrl` | ≤512 (a URL) | Link to the full generation report — a single self-contained HTML page holding the derivation. **Read-only**: you POST the HTML, the server sets this | A "how it was generated" button → `www.1024ex.com/alpha-report/{id}` | The two you write are three-state on every write that accepts them: **field omitted = unchanged**, `""` = cleared, a value = replaced. Never send `""` to mean "I have nothing to add" — that erases what is there. `reportUrl` takes only the clearing half (`""` removes the report); any other value is a 400 — see below. `description` is not deprecated and not a truncation of the markdown. Old clients and the feed rows read it alone, so write it as a standalone sentence, not as the first line of the body. ### Write the argument, not a slogan `descriptionMd` is 4000 characters because an alpha is a claim someone else is going to put money behind. A list whose whole justification is "semis look strong" is unfollowable: nobody can tell what would make it wrong, so nobody can tell when to get out. Spend the budget. What a usable body contains: - **The view** — the mechanism, not the direction. What is causing the move you are betting on, stated so it can be checked. - **The evidence** — the specific numbers you read and *when* you read them (a level, a rate, a print, an odds move). Date them; a follower arriving two days later needs to know what has gone stale. - **Why these legs, in this shape** — why this symbol and not the obvious neighbour, why the short leg is there, why the sizing is even. If a leg is a hedge, say what it hedges. - **The parameters, in words** — the entry, the stop and the target you encoded in `defaultCfg`, and the reasoning for the levels. The numbers are already machine-readable; what is missing is why 3% and not 8%. - **What would make this wrong** — the disconfirming event, and what you would do when it happens. This is the part everyone skips and the part that makes a list worth following. - **What you are not claiming** — the horizon, and anything the list does not cover. Write it in the language the user wrote to you in. Markdown headings, lists and tables all render; raw HTML does not (see below). Do not pad to the cap — 4000 characters is the ceiling, not the target — but a body under a few hundred characters almost always means the reasoning stayed in your head. ### Attaching the generation report The report is the third thing, and it is not a longer `descriptionMd`. `descriptionMd` is the argument you are making; the report is **the derivation** — the inputs, the screen you ran, the candidates you rejected and why, how the parameters were chosen, the backtest or the scan output. It is a whole page, an order of magnitude larger than the body, so it never enters the database and never travels with a list row — only its URL does. **You send the HTML, not a URL.** One call after the list exists: ```bash # 1. create the list, keep the id $ curl -X POST "$API/api/v1/alpha/lists" … -d '{"name":"AI infra long", …}' ⇒ { "list": { "id": "wl_9f2c…" } } # 2. post the page; the server stores it and sets reportUrl $ curl -X POST "$API/api/v1/alpha/lists/wl_9f2c…/report" \ -H "X-API-KEY: $KEY" -H "X-TIMESTAMP: $TS" -H "X-SIGNATURE: $SIG" \ -H "Content-Type: application/json" \ -d '{"html": "…"}' ⇒ { "id": "wl_9f2c…", "reportUrl": "https://…/alpha-reports/wl_9f2c…/report.html", "bytes": 48213 } ``` Why the two steps cannot collapse into one: the stored object is keyed by the list id, and the id is what the create call returns. `reportUrl` on `POST /alpha/lists` is therefore a 400 — deliberately, because silently dropping it would leave you reporting a report that was never attached. **`reportUrl` itself is not writable, and that is the point.** Sending a URL on any write is a 400 pointing back here. It reads as a needless restriction until you notice that only the platform's own credentials can create an object in that bucket: a caller who could set the column but not write the object would be publishing a button that 404s, with the server believing everything was fine. Posting the bytes means the same server writes the object, builds the URL and stores it, so the two cannot disagree. `"reportUrl": ""` still works and still means **remove the report** — that is the takedown path, and it is the one thing the field is still good for. ## Edit, unpublish, delete A published alpha is something other people execute. Changing one changes what they get, so each verb is separate and each is atomic. | Verb | Endpoint | Touches | | --- | --- | --- | | Replace the whole thing | `PUT /api/v1/alpha/lists/{id}` | legs + metadata + publish state | | Rename / re-thesis / (un)publish | `PATCH /api/v1/alpha/lists/{id}` | `name`, `description`, `descriptionMd`, `reportUrl`, `publish` — **never legs** | | Edit some legs | `PATCH /api/v1/alpha/lists/{id}/legs` | only the legs you name | | Tweak one leg's params | `PATCH /api/v1/watchlists/{id}/items/{item_id}` | one leg's `defaultCfg` / stance | | Attach / replace the report | `POST /api/v1/alpha/lists/{id}/report` | the stored HTML page and `reportUrl` | | Delete | `DELETE /api/v1/alpha/lists/{id}` | the list, its legs, its share token | | Retract a ticket | `DELETE /api/v1/alpha/tickets/{token}` | one ticket | Incremental leg edits address legs by the **same `legKey` the plan and execute calls use** — `perp::` and `pm::` — so one identity vocabulary spans authoring and execution: ```bash $ curl -X PATCH "$API/api/v1/alpha/lists/wl_9f2c…/legs" \ -H "X-API-KEY: $KEY" -H "X-TIMESTAMP: $TS" -H "X-SIGNATURE: $SIG" \ -H "Content-Type: application/json" -d '{ "upsert": [ { "itemKind": "perp", "symbol": "NVDA-USDC", "direction": "long", "defaultCfg": { "entry": "limit", "limitPctFromMark": -1, "exit": { "tpPct": 8, "slPct": 3 } } }, { "itemKind": "perp", "symbol": "AVGO-USDC", "direction": "long" } ], "remove": ["pm:35737:0"] }' ``` ```bash $ curl -X PATCH "$API/api/v1/alpha/lists/wl_9f2c…" -d '{"publish": false}' # unpublish $ curl -X DELETE "$API/api/v1/alpha/lists/wl_9f2c…" # delete $ curl -X DELETE "$API/api/v1/alpha/tickets/Qw81…" # retract # (all three signed like every other call) ``` ## Verified behavior - **The list id IS the watchlist id.** `/api/v1/alpha/lists/{id}` and `/api/v1/watchlists/{id}` address the same row — `alpha/lists` is the atomic publish/execute facade, [[watchlists]] is per-item CRUD. Same `wl_…` id, same 20-lists/account and 200-items/list caps, same lists your account sees in the web app. - **`POST /alpha/lists` is all-or-nothing.** A rejected leg fails the whole call and creates nothing — the alternative (create, then add legs one POST at a time) is what publishes a half-built basket when call 4 of 10 times out. - **`PUT /alpha/lists/{id}` REPLACES the legs**, it does not merge — legs absent from the body are gone. Replace semantics are deliberate: a leg you deleted must not survive in what the next person clones. To change metadata only, use `PATCH /alpha/lists/{id}`, which never touches legs no matter what you send it. - **`PATCH /alpha/lists/{id}/legs` is the incremental editor.** `upsert` matches on leg identity (`legKey`) — an existing leg keeps its item id and `sortOrder` and has its `defaultCfg` replaced; a new identity is appended. `remove` takes `legKey`s. Both arrays apply in one transaction, so a bad leg anywhere rejects the whole edit and the published list never shows a half-applied state. `"defaultCfg": null` in an upsert strips the params (leg becomes watch-only); omitting the field keeps the existing params. - **Removing a leg that is not there is a 400, not a silent no-op** — a typo'd `legKey` otherwise reads as "removed" and you would report a leg gone that is still live and still executable by others. - **`description` and `descriptionMd` are three-state on every write that takes them** — omitted keeps what is there, `""` clears it, a value replaces it. `PUT` follows the same rule, so a replace that forgets `descriptionMd` leaves the old body in place rather than wiping it. An empty PATCH body (no field at all) is a 400. - **`descriptionMd` caps at 4000 characters, `description` at 512, both counted in characters and both trimmed.** Over the cap is a 400 naming the field, never a truncation — a thesis cut mid-sentence is worse than a rejected call. - **The server neither parses nor sanitizes `descriptionMd`.** It is stored and returned verbatim, and a public list's body is attacker-controlled text. Render it with raw HTML disabled (react-markdown's default — do not enable `rehype-raw` for it) and never through `innerHTML`. - **`?q=` matches name + `description` + `descriptionMd`** on `/alpha/lists` and on `/alpha/search`'s list group, against the raw markdown (`#`, `-` and all — the server does not render it). This is why the body is worth writing: a list whose summary says "semiconductor momentum" is findable by "MU" only if MU appears in the text. - **`POST /alpha/lists/{id}/report` is the only way to attach one.** Body is `{"html": "…"}`, at most 5 MB, `canTrade`, owner-scoped (a list that is not yours is a 404, not a 403). One report per list at a fixed object key, so re-posting **replaces** it and the URL never changes — re-running your generator does not litter storage or move the link. The response gives you `reportUrl` and the byte count. - **A URL sent to any write field is a 400**, on create and on PATCH/PUT alike. The server builds and validates the URL itself, and the shape it enforces is exact: `https://` only, this environment's storage host (not "anything ending in `.supabase.co`"), the path `/storage/v1/object/public/alpha-reports/{this list's id}/`, and a filename of `[A-Za-z0-9._-]` ending in `.html` with no nesting. That rule set is why the column cannot be an open redirect and why one list cannot point at another's report — but it can only check where a URL points, never whether anything is there, which is the whole reason callers no longer supply one. - **Cloning carries `descriptionMd` and drops `reportUrl`.** The body is the argument, and a clone inherits it (truncated to the cap by characters, so a clone of a maximal body can stop mid-markdown); the report is the artifact of one specific generation run and its URL is keyed to the source list's id, so copying it would produce a link the validator itself would reject. A clone that needs a report needs its own. - **`publish: true` is the same act as `POST /watchlists/{id}/share`** — it mints the share token, sets `isPublic`, and enters the community feed. `publish: false` (PATCH or PUT) voids the token, exactly like `DELETE /watchlists/{id}/share`: the old token 404s forever, and republishing later mints a **new** one. Public payloads always return `shareToken: null`; the token is a credential, so store the one the publish response hands you. - **`DELETE /alpha/lists/{id}` deletes the list, cascades its legs, and voids the share token.** It is owner-scoped in SQL — someone else's id is a 404, never a 403 that confirms the list exists. Clones already taken are independent copies and survive; your `cloneCount` history goes with the row. - **Deleting or editing does not reach into anyone's positions.** People who already executed your list hold their own orders; unpublishing removes the recipe, not the trades. Say that plainly if a user asks you to "undo" a published alpha — the honest answer is that you can stop new executions, not the ones already placed. - **A list edited between plan and execute is exactly what `confirmLegKeys` guards against** — see [[alpha-action-list]]. Deleting or unpublishing invalidates in-flight plans: `execute` answers 404, and it checks that **before** placing anything, so a withdrawn list never costs anyone a leg. Editing one leg's params invalidates just that leg (`skipped: params_changed`); the rest of the plan still executes. - **Leg identity includes stance.** `NVDA-USDC` long and `NVDA-USDC` short are two legs, and `pm_market` legs are identified by `refId` + `outcomeIndex`. Sending the same identity twice in one `legs` array is a 400, not a silent dedup. - **`defaultCfg` caps at 2 KB serialized per leg** and is stored transparently — the server does not interpret the vocabulary at write time, so a typo (`tpPCT`) is accepted here and silently unresolvable at plan time. Author, then `POST /alpha/lists/{id}/plan` and read `warnings` / `skipped` before telling anyone the list is live. - **Edit one leg's params without republishing everything**: `PATCH /api/v1/watchlists/{id}/items/{item_id}` accepts `defaultCfg` alongside the stance fields, and either half may travel alone — send `defaultCfg` by itself and the stance is untouched. `defaultCfg` is three-state: **omitted = unchanged**, `null` = cleared, object = replaced. Item id and `sortOrder` survive. An empty body is a 400. - **Tickets are position-backed and green-only — for every `kind`.** `kind` is `called` | `fired` | `snapshot` | `bracket`, and a net PnL ≤ 0 is refused with 403 in all four. (Perp: unrealized while open, net once closed. Prediction: realized + unrealized.) A losing call is not mintable; publish a list if you want to post a view that is down. `includeClone` writes replayable setup params **only while the source position is still open** — the author must be holding what they told you to hold. - **The position must belong to you, and "you" means your user, not your key.** A ticket for a sub-account's position mints fine from the parent's key; someone else's position is 403. - **A minted ticket cannot be edited — there is no update endpoint, and that is the point.** It is a frozen, server-computed snapshot of a trade you were in; an editable ticket would endorse nothing. Wrong ticket → retract it and mint a new one. - **`DELETE /alpha/tickets/{token}` retracts your own ticket**, is idempotent, and is the only self-service takedown (governance can also revoke). Retracting drops it from the public feed and from `GET /alpha/tickets/{token}`; it stays visible in your own `?mine=true` history with `status: "revoked"`. Revoked and never-existed resolve to the same 404 — that identical answer is on purpose, so do not read 404 as "it was revoked". - Every mutation here — publish, edit, unpublish, delete, mint, retract — needs `canTrade` (the same permission every watchlist mutation needs). Reads need `canRead`. None of them can move funds. ## Composes Resolve symbols and market ids first — [[perp-markets]], [[prediction-discovery]]. Once published, your list is findable through [[alpha-search]] and executable through [[alpha-action-list]]. For per-item edits, sharing and cloning outside the alpha facade, see [[watchlists]].