File a signal (the canonical write)

POST

/api/predictions

• Protocol hub (Next.js) — federation, writes, receipts, market context

THE canonical signal write. One scored signal per user per market, first-call-locked — later additions go through POST /api/signals/{id}/events, never a rewrite. The Layer-4 snapshot (crowdYesAtSignal, timeToResolution) is captured at write time when the client omits it. Identity comes from the session or the operator key; the handle is never read from the body. Not CORS-open — a fork calls this from its own server route (DENPA_BASE_URL, default https://denpa.ai). Receipt at https://denpa.ai/receipts/<id>.

Authorizations

• operatorKey
• sessionCookie

Request Body ^required

object

marketId

required

string

direction

required

string

Allowed values: YES NO

priceAtPrediction

required

Price of the SIDE called, in bps. A NO call sends the NO price. The server normalises a NO call that arrived as the YES price when the YES snapshot is known.

integer

<= 10000

marketTitle

string

channelId

string | null

confidence

Operator self-assessed confidence.

integer | null

>= 1 <= 100

crowdYesAtSignal

Market YES probability (bps) at signal time. Captured server-side at write time when omitted.

integer | null

timeToResolution

Seconds from signal to expected resolution. Captured server-side when omitted.

integer | null

source

Client that filed the signal. Unknown values are stored as web.

string

Allowed values: web mobile farcaster embed

mediaAssetId

string | null

textTake

string | null

reach

Client-reported audience size for the take (untrusted; capped). The server coalesces it with its own live-viewer count for clobTokenId.

integer | null

clobTokenId

The market’s public CLOB token id — lets the server snapshot concurrent viewers as reach.

string | null

crowdLeanBps

Crowd YES lean (bps) shown to the user at signal time. Audit payload only — never written to the signal.

integer | null

Responses

200

Filed

object

ok

required

boolean

id

required

The signal id. Receipt at https://denpa.ai/receipts/<id>.

string format: uuid

400

Validation error. error names the missing or malformed field.

object

error

required

Stable machine-readable code (snake_case) or a short reason.

string

message

string

key

additional properties

any

401

unauthenticated

object

error

required

Stable machine-readable code (snake_case) or a short reason.

string

message

string

key

additional properties

any

409

market_closed — the market is settled or provisional · already_predicted — the caller’s signal on this market is locked.

object

error

required

Stable machine-readable code (snake_case) or a short reason.

string

message

string

key

additional properties

any

503

signal_service_unavailable · db_unavailable

object

error

required

Stable machine-readable code (snake_case) or a short reason.

string

message

string

key

additional properties

any