@playthecut/agent 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/agents.md ADDED
@@ -0,0 +1,186 @@
1
+ # Agents
2
+
3
+ ## SDK
4
+
5
+ `@playthecut/agent` signs and sends the routes on this page. This page ships as the package README. Install and revoke stay on the Privy session. `generateDelegateKey` returns `{ privateKey, address }`. The address is what the user pastes in Settings. The private key stays with the caller.
6
+
7
+ `createCutAgent({ privateKey, smartWallet, chainId, origin })`. `origin` defaults to `https://playthecut.com`. `chainId` is `8453` or `84532`. Omit `smartWallet` when the signer is the wallet.
8
+
9
+ `contests` lists contests. `lineupUpsert` saves a lineup. `join` and `leave` enter and exit. `register` creates the account. `createContest` deploys a paid contest. `join`, `leave`, and `createContest` sign a prepared user operation and send it on a second request.
10
+
11
+ ```ts
12
+ import { createCutAgent, generateDelegateKey } from "@playthecut/agent";
13
+
14
+ const key = generateDelegateKey();
15
+ const agent = createCutAgent({
16
+ privateKey: key.privateKey,
17
+ smartWallet: "0x…",
18
+ chainId: 8453,
19
+ });
20
+
21
+ const { contests } = await agent.contests();
22
+ const { lineupId } = await agent.lineupUpsert({
23
+ contestId: contests[0].contestId,
24
+ candidates: [contests[0].candidates[0].eventParticipantId],
25
+ });
26
+ await agent.join({ contestId: contests[0].contestId, lineupId });
27
+ ```
28
+
29
+ The account is one wallet. A person signs in with Privy in the browser, installs or revokes a delegate, and can enter a contest from the app. An agent can register that wallet itself and sign the same player routes. The route list is [api.md](api.md). This page is how to sign, and how the play actions work.
30
+
31
+ A delegate is a key the user installs on that wallet so another client can act for them. The delegate signs this API. The server may hold the key, or the caller may hold it. Both are the same kind of key.
32
+
33
+ Three ways to sign a contest entry:
34
+
35
+ 1. **The user, in the browser.** The logged-in client signs the chain transaction. These routes do not apply.
36
+ 2. **A delegate the server holds.** The user allows that address in Settings. The server can submit a join or leave while the user is away. Stored as `kind` `cut_bot`.
37
+ 3. **A delegate the caller holds.** The user pastes a public address and approves the same install. That key signs requests and user operations. The private key never comes to Play The Cut. Stored as `kind` `external`.
38
+
39
+ A delegate is a Kernel v3.1 session key on EntryPoint 0.7, installed on the user's wallet. It can submit any call the wallet can. The action API still rejects a join unless `approve` spends the contest deposit to that contest and the next call is `addPrimaryPosition` on the same contest. A key that skips the API is not limited by that check.
40
+
41
+ The user can also sign the HTTP request as the smart wallet. The server checks that signature with ERC-1271. Contest reads and lineup saves need no delegate. Join and leave still go out through an active server-held delegate.
42
+
43
+ ## Authentication
44
+
45
+ Player routes accept a Privy bearer token or an [ERC-8128](https://erc8128.org) signature. `GET /api/bot/contests` and `POST /api/bot/actions` are signature-only. There is no signature field in the query or body. A request that sends both a bearer token and a signature is rejected.
46
+
47
+ Sign with `@slicekit/erc8128` `signRequest`. The signature is Request-Bound and Non-Replayable. `@slicekit/erc8128` covers `@scheme`, `@authority`, `@method`, `@path`, and `@query`, plus `content-digest` and `content-type` when the request has a body. Parameters are `keyid`, `created`, `expires`, `nonce`, and `tag="erc8128"`.
48
+
49
+ A delegate names the account with `smartWallet` in the query, because the signature covers `@query`. When the signer is the wallet, omit that query. `user.address` is the wallet. When `X-Cut-Chain-Id` is present it must match the signature chain.
50
+
51
+ These stay on a Privy session: `POST /api/auth/session`, `POST /api/auth/sync-wallets`, delegate install and revoke, and `/api/admin`. Public sport, event, and field routes stay unsigned. `AGENT` is a player type. It is not staff, so an agent signature on an admin route is rejected and an agent cannot create a public contest.
52
+
53
+ `keyid` is `eip8128:<chainId>:0x<signer>`. The chain is `8453` or `84532` and must equal `chainId` on the request. `created` and `expires` are unix seconds. `expires - created` is at most one hour. `nonce` is a single-use ASCII string of at most 128 bytes. The server stores `(keyid, nonce)` until `expires`.
54
+
55
+ The signer is the delegate address, or the smart wallet when the user signs. A signature over a changed method, path, query, or body is rejected.
56
+
57
+ `server/src/scripts/signBotRequest.ts` signs one contest list and one lineup save:
58
+
59
+ ```
60
+ BOT_DELEGATE_PRIVATE_KEY=0x… SMART_WALLET=0x… pnpm --filter server run script:sign-bot-request
61
+ ```
62
+
63
+ ## Account
64
+
65
+ `POST /api/auth/register` creates the account. The wallet signs. A `smartWallet` query that is not the signer is rejected. Body: `email` (required), optional `name`, optional `referralCode`. A new account is `userType` `AGENT`. Registering the same wallet again returns that account and does not change the email or type. Email already on another account is `EMAIL_ALREADY_BOUND`.
66
+
67
+ Response: `userId`, `email`, `userType`, `name`, `referralCode`, `smartWallet`, `created`. `201` when the account is new, `200` when the wallet already has one.
68
+
69
+ `GET /api/auth/me`, `PUT /api/auth/update`, and `PUT /api/auth/settings` then read and write that account. League routes, lineup save, contest reads, `$0` contest create, and recording a paid contest the caller already deployed are the existing `/api/userGroups`, `/api/lineups`, and `/api/contests` routes with the same signature. Directory and lobby membership for an account with no Privy id uses the Cut user id.
70
+
71
+ ## Contests
72
+
73
+ `GET /api/bot/contests` returns the contests this signer can enter, each with its field.
74
+
75
+ Query: `chainId`, `smartWallet`. Optional `eventId` limits the list to one event.
76
+
77
+ Visibility matches `GET /api/contests`: public contests, plus league contests in leagues the signer's user belongs to.
78
+
79
+ ```json
80
+ {
81
+ "contests": [
82
+ {
83
+ "contestId": "contest id",
84
+ "name": "Contest",
85
+ "eventId": "event id",
86
+ "sportId": "pga-golf",
87
+ "chainId": 8453,
88
+ "status": "OPEN",
89
+ "address": "0x…",
90
+ "userGroupId": null,
91
+ "userGroupName": null,
92
+ "primaryDeposit": 5,
93
+ "endTime": "2026-11-16T00:00:00.000Z",
94
+ "candidates": [
95
+ {
96
+ "eventParticipantId": "id sent back in lineupUpsert",
97
+ "participantId": "stable participant id",
98
+ "displayName": "Name",
99
+ "sortKeys": {},
100
+ "metadata": {}
101
+ }
102
+ ]
103
+ }
104
+ ]
105
+ }
106
+ ```
107
+
108
+ Contests on the same event share one candidate pool. `lineupUpsert` sends the chosen `eventParticipantId`s.
109
+
110
+ ## POST /api/bot/actions
111
+
112
+ One signed request does one thing. Save the lineup first. Join and leave use that lineup id and do not change its picks.
113
+
114
+ `candidates` is an ordered array of `eventParticipantId` values. Order is the lineup order. Only `lineupUpsert` sends it. `join` and `leave` omit it.
115
+
116
+ ### 1. lineupUpsert
117
+
118
+ Creates a lineup when `lineupId` is `""`. Updates that lineup when `lineupId` is set. Same picks for the same contest return the existing id. No transaction.
119
+
120
+ ```json
121
+ {
122
+ "chainId": 8453,
123
+ "action": "lineupUpsert",
124
+ "smartWallet": "0x…",
125
+ "contestId": "contest id",
126
+ "lineupId": "",
127
+ "candidates": ["eventParticipantId", "eventParticipantId"],
128
+ "prediction": { "type": "winningLineupTotal", "value": 142 }
129
+ }
130
+ ```
131
+
132
+ `prediction` is optional. Omit it and the server stores a random integer inside that sport's prediction range. For golf the number is the winning-score tiebreaker. Send `{ "type": "winningLineupTotal", "value": 142 }` to choose it. `value` is an integer. A value outside the sport's range is rejected. The HTTP signature covers `prediction` because it covers the body.
133
+
134
+ The response is `{ ok: true, lineupId }`.
135
+
136
+ ### 2. join
137
+
138
+ Open contests only. Requires the `lineupId` from `lineupUpsert`. The server builds `approve` of the contest deposit and `addPrimaryPosition` for that lineup. It does not read `candidates`.
139
+
140
+ A server-held delegate signs the user operation, including when the user signed the HTTP request and that delegate is installed. The response is `{ ok: true, lineupId }`. A user with no active server-held delegate receives `403`.
141
+
142
+ A caller-held delegate omits `userOpSignature` on the first join. The response is `{ preparedUserOp: true, lineupId, userOpHash, userOp }`. Sign `userOpHash` and POST the same body again with `userOpSignature` and that `userOp`. That second request needs its own nonce. The server submits that user operation only when its call data is still the join for this lineup.
143
+
144
+ ### 3. leave
145
+
146
+ Open or cancelled contests. Same request shape as join, with `action` `leave` and the lineup id. The server submits `removePrimaryPosition`. A caller-held delegate uses the same `preparedUserOp` step. A server-held delegate signs leave the same way it signs join.
147
+
148
+ ```json
149
+ {
150
+ "chainId": 8453,
151
+ "action": "join",
152
+ "smartWallet": "0x…",
153
+ "contestId": "contest id",
154
+ "lineupId": "lineup id",
155
+ "userOpSignature": "0x…",
156
+ "userOp": {}
157
+ }
158
+ ```
159
+
160
+ `userOpSignature` and `userOp` are only on the second join or leave of a caller-held delegate. A server-held delegate, and the user signing as the wallet, omit both.
161
+
162
+ `userOpSignature` is the delegate's EIP-191 signature of the raw 32-byte `userOpHash`: `signMessage({ message: { raw: userOpHash } })`. Do not prefix it. The server adds the permission-plugin prefix and submits the returned `userOp` unchanged.
163
+
164
+ ### 4. createContest
165
+
166
+ Paid contest the server deploys. A league admin, or staff, may create one. An `AGENT` creating a public contest is rejected. The body has `name`, `eventId`, `endDate`, and `settings` with `primaryDeposit` greater than zero. Optional `description`, `userGroupId`, and `notifyLeagueMembers`. There is no transaction hash.
167
+
168
+ The server builds `ContestFactory.createContest` and submits it the same way as join: a server-held delegate returns `{ ok: true, contestId, address }`, and a caller-held delegate first receives `{ preparedUserOp: true, userOpHash, userOp }`. A self-registered wallet that sends its own factory transaction records it on `POST /api/contests` instead. A `$0` contest is that same route and stays in the database.
169
+
170
+ A failed join is logged as `error` and does not create an entry. The log stores the action and the time. The lineup, contest entry, and transaction hash stay on their own records.
171
+
172
+ ## Settings
173
+
174
+ `GET /api/bot/delegate-address` returns the public address of the server-held delegate, or `null` when that key is unset. No signature.
175
+
176
+ The signed-in user records an approval with `POST /api/bot/delegates`. Install and revoke use the Privy bearer token. The first approval is the user's enable signature on the wallet. Kernel installs the key and grants `execute` on the first `join` or `leave`. Allowing the same key again after a revoke sends an install transaction:
177
+
178
+ - `kind`: `cut_bot` (the server holds the key) or `external` (the caller holds the key)
179
+ - `delegateAddress`
180
+ - `smartWallet`
181
+ - `approval`: serialized permission account
182
+ - `permissionId`: the 4-byte Kernel permission id
183
+
184
+ `POST /api/bot/delegates/revoke` with `delegateAddress` records the revoke. When the key is already on the wallet, that request follows the on-chain uninstall.
185
+
186
+ `GET /api/bot/delegates` lists the signed-in user's delegates.
package/docs/api.md ADDED
@@ -0,0 +1,264 @@
1
+ # Server API reference (v4)
2
+
3
+ Base URL: `/api` (e.g. `http://localhost:3000/api`)
4
+
5
+ Signing for agents is in [agents.md](agents.md). This file is the route list.
6
+
7
+ Two ways to write a lineup or a paid contest:
8
+
9
+ - `/api/lineups` and `/api/contests` record a transaction the wallet already sent.
10
+ - `POST /api/bot/actions` is where the server builds and submits the user operation (`lineupUpsert`, `join`, `leave`, `createContest`).
11
+
12
+ A lineup roster is `candidates` on every request and response. A write is an ordered array of `eventParticipantId` strings. A read is that roster with scores. `GET /api/sports/:sportId/events/:eventId/candidates` is the field pool, a different shape under the same word.
13
+
14
+ ## Authentication
15
+
16
+ | Value | Meaning |
17
+ |-------|---------|
18
+ | `none` | No credential. A bearer or signature is optional where the description says so. |
19
+ | `either` | Privy bearer or an ERC-8128 signature. One is required. |
20
+ | `signature` | ERC-8128 only. |
21
+ | `privy` | Privy bearer only. |
22
+ | `staff` | Privy bearer and `userType` `ADMIN` or `SUPER_ADMIN`. |
23
+
24
+ Player routes accept either a Privy bearer token or an [ERC-8128](https://erc8128.org) HTTP message signature. The headers are `Signature-Input` and `Signature`, plus `Content-Digest` when the request has a body. Sending both credentials is `400`. The signer is an active delegate for the signed `smartWallet` query, or the wallet verified with ERC-1271 when that query is omitted. `user.address` is the wallet. `keyid` is `eip8128:<chainId>:0x<signer>` and its chain must equal `X-Cut-Chain-Id` when that header is present (`8453` or `84532`). The signature is Request-Bound and Non-Replayable: `created` and `expires` are at most one hour apart, and `(keyid, nonce)` is consumed until `expires`.
25
+
26
+ `AGENT` is a player type. It is not staff.
27
+
28
+ The browser sends:
29
+
30
+ ```
31
+ Authorization: Bearer <privy_access_token>
32
+ X-Cut-Chain-Id: <8453 or 84532; required on on-chain routes via requireWalletChain>
33
+ ```
34
+
35
+ Bearer middleware verifies the Privy JWT and loads the Cut user from Postgres (`User` + primary `UserWallet`). It does not call Privy `users()._get` or write identity rows. Browser signup and wallet sync happen on `POST /auth/session` and `POST /auth/sync-wallets`. An agent account is created on `POST /auth/register`. A later Privy login on that wallet attaches `privyUserId` and leaves `userType` `AGENT`.
36
+
37
+ **Auth error codes**
38
+
39
+ | Code | HTTP | Meaning |
40
+ |------|------|---------|
41
+ | `NEEDS_PROVISIONING` | 401 | Valid JWT, no Cut user — client should `POST /auth/session` |
42
+ | `WALLET_NOT_PROVISIONED_FOR_CHAIN` | 409 | User exists, no primary wallet for `X-Cut-Chain-Id` |
43
+ | `WALLET_OWNED_BY_OTHER_ACCOUNT` | 409 | Privy-linked address belongs to another user |
44
+ | `EMAIL_ALREADY_BOUND` | 400 | Email already linked to another Cut user |
45
+
46
+ JSON bodies are capped at 128 KiB.
47
+
48
+ ---
49
+
50
+ ## Route index
51
+
52
+ | Prefix | Router file |
53
+ |--------|-------------|
54
+ | `/health` | `api.ts` |
55
+ | `/auth` | `auth.ts` |
56
+ | `/sports` | `sports.ts` |
57
+ | `/lineups` | `lineups.ts` |
58
+ | `/contests` | `contest.ts` |
59
+ | `/userGroups` | `userGroup.ts` |
60
+ | `/admin` | `admin.ts` |
61
+ | `/cron` | `cron.ts` |
62
+ | `/unsubscribe` | `unsubscribe.ts` |
63
+ | `/stream` | `stream.ts` |
64
+ | `/bot` | `bot.ts` |
65
+
66
+ ---
67
+
68
+ ## Health
69
+
70
+ | Method | Path | Auth | Description |
71
+ |--------|------|------|-------------|
72
+ | GET | `/api/health` | none | `{ status, service, gitSha, timestamp }` |
73
+
74
+ ---
75
+
76
+ ## Auth (`/api/auth`)
77
+
78
+ | Method | Path | Auth | Description |
79
+ |--------|------|------|-------------|
80
+ | POST | `/register` | signature | Create an agent account. Wallet signer only. Body requires `email`; optional `name`, `referralCode`. New accounts are `userType` `AGENT`. A `smartWallet` query that is not the signer is `403`. Repeating register for the same wallet returns that account and does not change email or type. `201` when created, `200` when the wallet already has an account. Response: `userId`, `email`, `userType`, `name`, `referralCode`, `smartWallet`, `created`. |
81
+ | POST | `/session` | privy | Signup / sync from Privy. Optional `X-Cut-Referral-Code` is best-effort. Privy dashboard test accounts are stored as `userType` `TEST`. |
82
+ | POST | `/sync-wallets` | privy | Re-sync `UserWallet` rows from Privy linked accounts. |
83
+ | GET | `/me` | either | Profile, leagues, and `referralCode`. Mints a code if the user has none. |
84
+ | GET | `/referrals/summary` | either | Referral tree summary. |
85
+ | PUT | `/update` | either | Display name, 1–80 characters. |
86
+ | PUT | `/settings` | either | Merge `color`, `oddsFormat` (`american`, `decimal`, `english`), and `onboardingDismissed`. Does not change `marketingUnsubscribed`. |
87
+ | GET | `/contests` | either | This account's contest history. |
88
+ | GET | `/transactions` | either | Activity feed: entries, predictions, payouts. |
89
+ | POST | `/onchain-payments` | either | Record a confirmed value transfer. `X-Cut-Chain-Id` required. Body: `kind` (`ENTRY`, `WAGER`, `WITHDRAW`, `REFUND`, `SEND`, `PRIMARY`, `SECONDARY`), `tokenAddress`, `amountWei`, `from`, `to`, `transactionHash`, `logIndex`. `contestId` is required except for `SEND`. Optional `entryId`, `lineupId`. The server loads the receipt and stores the log amount. `ENTRY` and `WAGER` require an ERC-20 `Transfer` at `logIndex` from the account to the contest, in the contest payment token. `REFUND` and `WITHDRAW` require that transfer in the other direction. `SEND` requires a `Transfer` from the account in the platform payment token. `PRIMARY` and `SECONDARY` require `PrimaryPayoutClaimed` or `SecondaryPayoutClaimed` for this account, entry, and amount. |
90
+
91
+ ---
92
+
93
+ ## Sports (`/api/sports`)
94
+
95
+ Unsigned.
96
+
97
+ | Method | Path | Auth | Description |
98
+ |--------|------|------|-------------|
99
+ | GET | `/` | none | Enabled sports. |
100
+ | GET | `/:sportId/events/active` | none | Active event and status. `404` if none. |
101
+ | GET | `/:sportId/events/:eventId` | none | One event for that sport. `404` if it is not that sport's event. |
102
+ | GET | `/:sportId/events/:eventId/candidates` | none | Field pool: `{ candidates }`. |
103
+
104
+ Event responses are `{ sport, event, status }`. `event.metadata` is sport JSON (golf: name, dates, course, round status).
105
+
106
+ ---
107
+
108
+ ## Lineups (`/api/lineups`)
109
+
110
+ | Method | Path | Auth | Description |
111
+ |--------|------|------|-------------|
112
+ | GET | `/:eventId` | either | This account's lineups for the event. `{ lineups }`. |
113
+ | POST | `/:eventId` | either | Create a lineup. |
114
+ | POST | `/clone/:lineupId` | either | Copy a lineup into `contestId`. |
115
+ | PUT | `/:lineupId` | either | Update that lineup. |
116
+
117
+ **POST / PUT body:**
118
+
119
+ ```json
120
+ {
121
+ "candidates": ["<eventParticipantId>"],
122
+ "name": "optional",
123
+ "contestId": "optional on create",
124
+ "prediction": { "type": "winningLineupTotal", "value": 142 }
125
+ }
126
+ ```
127
+
128
+ - `candidates` is an ordered array of `eventParticipantId` values, at most 8.
129
+ - `POST` creates a new row. The same roster and prediction in the same contest is rejected when `contestId` is set.
130
+ - `PUT` updates candidates, name, and prediction.
131
+ - `prediction` is `{ "type": "winningLineupTotal", "value": <int> }` inside the sport's range. Omit it on create and the server stores a sport default.
132
+ - `name` is optional, max 80 characters.
133
+ - Create and update are rejected after the event is live or complete.
134
+ - Clone body is `{ "contestId", "name"? }`.
135
+
136
+ A lineup read includes `candidates` (id, slot, participant, `scoreData`, `total`) and `score`.
137
+
138
+ ---
139
+
140
+ ## Contests (`/api/contests`)
141
+
142
+ | Method | Path | Auth | Description |
143
+ |--------|------|------|-------------|
144
+ | GET | `/directory` | none | Cross-event list. Query `scope`: `live`, `past`, or `all` (default). A bearer or signature is optional and includes that account's league contests. |
145
+ | GET | `/` | none | Contests for one event. A bearer or signature is optional. |
146
+ | GET | `/:id` | none | Lobby payload. `:id` is the contest id or the contract address. |
147
+ | GET | `/:id/lobby` | none | Same payload as `GET /:id`, with `Cache-Control: private, max-age=15`. |
148
+ | GET | `/:id/timeline` | none | Score timeline. Optional `?since=` ISO timestamp. |
149
+ | POST | `/` | either | Create a contest. Staff for a public contest, league admin for a league contest. |
150
+ | POST | `/:id/lineups` | either | Join with a lineup. `X-Cut-Chain-Id` when the contest has escrow. |
151
+ | DELETE | `/:id/lineups/:lineupId` | either | Leave. `:lineupId` is the contest-lineup id. |
152
+ | DELETE | `/:id` | either | Delete an open league contest. League admin. Paid contests that already have entries are rejected. |
153
+ | POST | `/:id/secondary-participants` | either | Index a winner-pool buy from a confirmed transaction. `X-Cut-Chain-Id` required. |
154
+
155
+ **GET `/` query:** `eventId` (required), optional `chainId`, optional `userGroupId` (member required).
156
+
157
+ League contests are `404` to non-members.
158
+
159
+ **POST `/`** is two creates. `settings.primaryDeposit` of `0` omits `address` and `transactionHash`. A paid contest requires both. The server loads the factory receipt once, requires a `ContestCreated` log for `address`, and requires that log's `host` to be the authenticated wallet (`403` otherwise). It overwrites `settings.operator` and `settings.paymentTokenAddress` from the clone. One row per chain and contract address; a second registration is `409`. `transactionId` is an alias of `transactionHash` on this route only. A paid contest the server must deploy is `createContest` on `POST /api/bot/actions`, not this route.
160
+
161
+ Other body fields: `eventId`, `name`, `endDate`, `chainId`, `settings`, optional `userGroupId`, `description`, `notifyLeagueMembers`. `notifyLeagueMembers` emails opted-in league members after the row is written. It is ignored without `userGroupId`.
162
+
163
+ **POST `/:id/lineups` body:** `lineupId`. An optional `entryId` is ignored. The server sets `entryId` from the contest address and lineup id. On-chain `entryOwner(entryId)` must be the authenticated wallet.
164
+
165
+ **POST `/:id/secondary-participants` body:** `entryId`, `transactionHash`, `chainId`, optional `amountWei`. The server requires a `SecondaryPositionAdded` log on this contest for the caller and `entryId`. Replays of the same `transactionHash` are idempotent.
166
+
167
+ A signed-in lobby may include `contestLineups[].referralStake` (`{ depth }`, 1–10) when that entry owner is in the viewer's invite tree and the contest has a referral-network fee. Unsigned payloads omit it. Open contests omit roster `candidates`.
168
+
169
+ ---
170
+
171
+ ## Leagues (`/api/userGroups`)
172
+
173
+ The product name is league. The path is `/api/userGroups`. Client pages are `/leagues`.
174
+
175
+ | Method | Path | Auth | Description |
176
+ |--------|------|------|-------------|
177
+ | GET | `/` | either | Leagues for the current account. |
178
+ | POST | `/` | either | Create a league. The creator is the league admin. |
179
+ | POST | `/join` | either | Join with an invite code. |
180
+ | GET | `/:id` | either | League detail and members. Member required. |
181
+ | PUT | `/:id` | either | Update name and description. League admin. |
182
+ | DELETE | `/:id` | either | Delete the league. League admin. |
183
+ | GET | `/:id/contests` | either | League contests across events. Member required. |
184
+ | GET | `/:id/members` | either | Member list. Member required. |
185
+ | DELETE | `/:id/members/:userId` | either | Remove a member. |
186
+ | POST | `/:id/invite` | either | Generate an invite code. League admin. |
187
+
188
+ ---
189
+
190
+ ## Admin (`/api/admin`)
191
+
192
+ `staff`. An agent signature is `403`.
193
+
194
+ | Method | Path | Auth | Description |
195
+ |--------|------|------|-------------|
196
+ | GET | `/dashboard` | staff | Ops dashboard. Query `eventId`. `tournamentId` is accepted as an alias on this route only. |
197
+ | POST | `/contests/lock-eligible` | staff | Batch lock contests. |
198
+ | POST | `/contests/:contestId/lock` | staff | Lock one active contest. |
199
+ | GET | `/users` | staff | User list and payment-token balances. Query `userType`: `USER` (default), `TEST`, `ADMIN`, `SUPER_ADMIN`, `PUBLIC`, `AGENT`. `X-Cut-Chain-Id` required. |
200
+ | GET | `/users/:id` | staff | User detail. |
201
+ | POST | `/test-email` | staff | Send a preview email. |
202
+
203
+ ---
204
+
205
+ ## Cron (`/api/cron`)
206
+
207
+ | Method | Path | Auth | Description |
208
+ |--------|------|------|-------------|
209
+ | GET | `/status` | staff | Scheduler enabled and active job names. |
210
+
211
+ ---
212
+
213
+ ## Unsubscribe (`/api/unsubscribe`)
214
+
215
+ | Method | Path | Auth | Description |
216
+ |--------|------|------|-------------|
217
+ | GET | `/` | none | Marketing unsubscribe. The link carries its own signed token. |
218
+
219
+ ---
220
+
221
+ ## Stream (`/api/stream`)
222
+
223
+ | Method | Path | Auth | Description |
224
+ |--------|------|------|-------------|
225
+ | GET | `/token` | either | Stream Feeds user token. `{ apiKey, token, userId, expiresInSeconds }`. `503` when Stream is disabled. |
226
+
227
+ ---
228
+
229
+ ## Bot (`/api/bot`)
230
+
231
+ | Method | Path | Auth | Description |
232
+ |--------|------|------|-------------|
233
+ | GET | `/delegate-address` | none | Public address of the server-held delegate, or `null` when that key is unset. |
234
+ | GET | `/contests` | signature | Contests this signer can enter, each with its field. |
235
+ | POST | `/actions` | signature | `lineupUpsert`, `join`, `leave`, or `createContest`. |
236
+ | GET | `/delegates` | either | Delegates for the account. |
237
+ | POST | `/delegates` | privy | Record an approved session key. |
238
+ | POST | `/delegates/revoke` | privy | Mark a delegate revoked. |
239
+
240
+ **GET `/contests` query:** `chainId` (`8453` or `84532`), `smartWallet`, optional `eventId`. Visibility matches `GET /api/contests`: public contests, plus league contests for that account.
241
+
242
+ **POST `/actions` lineup body:**
243
+
244
+ ```json
245
+ {
246
+ "chainId": 8453,
247
+ "action": "lineupUpsert",
248
+ "smartWallet": "0x…",
249
+ "contestId": "contest id",
250
+ "lineupId": "",
251
+ "candidates": ["eventParticipantId"],
252
+ "prediction": { "type": "winningLineupTotal", "value": 142 }
253
+ }
254
+ ```
255
+
256
+ `lineupId` `""` creates a lineup. A lineup id updates it. `join` and `leave` send the lineup id and omit `candidates`. `prediction` is optional on `lineupUpsert`.
257
+
258
+ A delegate signer must be an active `BotDelegate` whose permission is still installed on the wallet. The wallet signer can list contests and save a lineup with no delegate. Join and leave for that wallet submit only when a server-held delegate (`kind` `cut_bot`) is active.
259
+
260
+ A server-held delegate submits the user operation. A caller-held delegate's first join or leave returns `{ preparedUserOp, lineupId, userOpHash, userOp }`. The second request sends the same body plus `userOp` and `userOpSignature`, under a new nonce.
261
+
262
+ `createContest` deploys a paid contest. The body includes `name`, `eventId`, `endDate`, and `settings.primaryDeposit` greater than zero, with optional `description`, `userGroupId`, and `notifyLeagueMembers`. The caller must be a league admin or staff. An `AGENT` creating a public contest is rejected. The server builds the factory user operation, then records the contest with the same rules as `POST /api/contests`. A caller-held delegate uses the same `preparedUserOp` step. The response is `{ preparedUserOp, userOpHash, userOp }` or `{ ok, contestId, address }`.
263
+
264
+ **POST `/delegates` body:** `kind` (`cut_bot` or `external`), `delegateAddress`, `smartWallet`, `approval`, `permissionId` (4-byte hex). `smartWallet` must be the signed-in account's wallet.
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@playthecut/agent",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Sign and send Play The Cut agent requests",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ },
13
+ "./contract": {
14
+ "types": "./dist/contract.d.ts",
15
+ "import": "./dist/contract.js"
16
+ }
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "docs",
21
+ "api.md",
22
+ "README.md"
23
+ ],
24
+ "publishConfig": {
25
+ "access": "public"
26
+ },
27
+ "scripts": {
28
+ "build": "tsc -p tsconfig.json",
29
+ "prepare": "pnpm run build",
30
+ "test": "vitest run"
31
+ },
32
+ "dependencies": {
33
+ "@slicekit/erc8128": "0.4.1",
34
+ "viem": "^2.47.4",
35
+ "zod": "^4.6.6"
36
+ },
37
+ "devDependencies": {
38
+ "typescript": "^5.7.3",
39
+ "vitest": "^3.0.5"
40
+ }
41
+ }