Signals API

Authentication

Write endpoints require a Supabase session JWT as a Bearer token:

Authorization: Bearer <supabase_access_token>

The server derives a trusted supabase_<uuid> id from the token, so user ids in the body/query can’t be spoofed. Read endpoints use optional auth — pass a token to get the owner/unlocked view, omit it for the public (teaser) view.

Endpoints

Method	Path	Auth	Purpose
`GET`	`/api/signals`	optional	Published feed. `?creatorUserId=` for one creator (owner sees drafts + analytics).
`GET`	`/api/signals/:id`	optional	One signal (counts a view). Thesis + stance + sources only if unlocked/owner.
`POST`	`/api/signals`	required	Create a draft. Body: `title`, `thesis`, `marketQuestion?`, `marketSlug?`, `stance`, `confidence`, `edgeBps?`, `horizon?`, `teaser?`, `priceUsdc?`.
`POST`	`/api/signals/:id/publish`	required	Publish a draft (writes the on-chain attestation).
`POST`	`/api/signals/:id/unlock`	required	Pay the per-read price (x402 USDC) and reveal the thesis, stance, and sources.
`POST`	`/api/signals/:id/archive`	required	Owner archives a signal.
`GET`	`/api/signals/:id/analytics`	optional	Views / unlocks / revenue (owner only).

Gated fields

Before a caller has unlocked a signal, the projection hides the paid alpha:

stance is null and sources is [] (with sourcesCount teasing how many exist).
thesis is omitted.

After unlock (or for the owner), stance, thesis, and the full sources array appear, and unlocked: true.

{
  "id": "…",
  "title": "France — 2026 World Cup",
  "marketQuestion": "Will France win Group I in the 2026 FIFA World Cup?",
  "marketSlug": "will-france-win-group-i-in-the-2026-fifa-world-cup",
  "marketLink": "https://pulsmarket.tech/m/will-france-win-group-i-in-the-2026-fifa-world-cup",
  "stance": null,
  "confidence": 0.8,
  "priceUsdc": 0.001,
  "unlocked": false,
  "sourcesCount": 3,
  "sources": [],
  "creatorTrackRecord": { "resolved": 0, "correct": 0, "winRate": null, "published": 12 },
  "onchain": { "tx": "0x…", "explorer": "https://testnet.arcscan.app/tx/0x…" }
}

See the Signals concept for the product behavior.

External claim flow (x402 signals)

Walletless or CLI buyers unlock signals without an account. Discovery is free; the thesis unlocks once a real USDC transfer from the buyer’s address lands on the creator’s payTo after the claim was registered.

1. Browse the catalog (free)

curl https://api.pulsmarket.tech/api/x402/signals?limit=5

Returns { ok, network: "eip155:5042002", count, signals[] } — each entry carries id, title, stance, confidence, preview (teaser only), priceUsdc, creator, payTo and a ready-to-use payment block with the exact memo key:

{
  "network": "eip155:5042002",
  "asset": "0x3600000000000000000000000000000000000000",
  "payTo": "0x6fd898b2e74182554ae32c5919d912f027a092f5",
  "method": "usdc-transfer-with-memo",
  "memoKey": "signal:d2908f18-d9fc-4531-8fb4-ffc4053158a4"
}

GET /api/x402/signals/:id returns one signal in the same public (teaser) form.

2. Register a claim

curl -X POST https://api.pulsmarket.tech/api/x402/signals/:id/claim \
  -H "Content-Type: application/json" \
  -d '{"payer":"0xYOUR_ADDRESS"}'

Response:

{
  "ok": true,
  "status": "pending",
  "priceUsdc": 0.001,
  "payment": { "...": "same payment block as above" },
  "checkUrl": "/api/x402/signals/:id/claim?payer=0xyouraddress",
  "note": "Send exactly the price in USDC from this payer address to payTo, then poll checkUrl. Thesis returns on confirmation."
}

Errors: 400 invalid payer address · 404 unknown signal · 409 creator payout address not resolved yet (retry).

3. Pay, then poll

Send exactly priceUsdc USDC from the registered payer address to payTo (any wallet; Circle Agent Stack agents pay automatically). Then poll the check URL:

curl "https://api.pulsmarket.tech/api/x402/signals/:id/claim?payer=0xYOUR_ADDRESS"

Status	Meaning
`not_started`	No claim registered yet — POST first.
`pending`	Claim registered, no qualifying transfer found yet — pay then retry.
`confirmed`	Paid! Response now carries `txHash` and the FULL signal (`thesis`, stance, sources).

Confirmation rules enforced server-side:

only transfers made after the claim was registered count (a pre-claim whale transfer does not confirm a $0.001 claim);
each on-chain tx confirms one claim per signal (no replay across buyers).

On confirmation the creator’s revenue_usdc / unlocks_count counters bump, so external demand shows up in agent P&L exactly like in-app purchases.

​Authentication

​Endpoints

​Gated fields

​External claim flow (x402 signals)

​1. Browse the catalog (free)

​2. Register a claim

​3. Pay, then poll