Integration guide

# Connect your chain (10–15 min, no app code)

Primary path for all on-chain operators:

1. Open Dashboard → Connect your chain
   https://wagerly.tech/dashboard/setup

2. Choose market type
   - Prediction market → Polymarket full (Polygon, pre-filled addresses)
   - Crypto casino → generic contract on Base
   - Other on-chain → pick chain + contract address

3. Copy into Alchemy (Address Activity webhook)
   URL:    POST https://wagerly.tech/api/v1/ingest/{tenantId}/evm
   Header: Authorization: Bearer <ingest_secret>
   Watch:  contract addresses shown in the wizard

4. Paste Alchemy signing key in the wizard → wait for Retention live

5. Optional on finish step
   - Enable Dormancy (pure inactivity) trigger
   - Set outbound webhook URL

No API key or SDK required for core retention. Player ID = {chainId}:0xWallet.

Solana: Settings → Advanced connectors → Solana
Advanced HTTP/Supabase: Settings → Advanced connectors

# Go-live checklist

1. Open Dashboard → Connect your chain (/dashboard/setup)
2. Choose market type and configure Alchemy Address Activity webhook
3. Paste signing key → confirm Integration health shows "Retention live"
4. Optional: enable dormancy trigger + outbound webhook on wizard finish step
5. Polymarket: use prediction market path (Exchange + USDC pre-filled)

Advanced: Settings → Advanced connectors for HTTP, Supabase, Solana, manual EVM.

See also: #connect-chain · #metrics · #webhooks · #operations · #events

# GGR / NGR metrics

Wagerly computes per-wallet rollups from ingested wager events:

| Metric | Definition | Source events |
|--------|------------|---------------|
| GGR (7d / 30d) | Gross gaming revenue — total wager handle | SUM(handle) on wager_placed |
| NGR (7d / 30d) | Net gaming revenue — operator margin | SUM(net_margin) on wager_settled |

Where to view:
  - Dashboard → Overview: tenant 7d GGR / NGR rollup
  - Dashboard → Players: per-wallet 7d GGR / NGR columns
  - Player detail: 7d + 30d + lifetime GGR/NGR cards

Trigger webhook payload (financials block):
  ggr_7d, ngr_7d, ggr_30d, ngr_30d
  lifetime_handle, lifetime_net_margin
  handle_7d, handle_30d

# Ingest authentication (required)

Every webhook ingest route rejects unauthenticated requests:

  Authorization: Bearer <ingest_secret>

Routes:
  POST /api/v1/ingest/{tenantId}           — universal JSON
  POST /api/v1/ingest/{tenantId}/evm       — Alchemy / QuickNode / raw logs
  POST /api/v1/ingest/{tenantId}/supabase  — Supabase DB webhook
  POST /api/v1/ingest/{tenantId}/solana    — Helius / raw Solana txs
  POST /api/v1/ingest/{tenantId}/test-mapping — field mapping preview

Copy or rotate ingest_secret in Settings → Credentials or Advanced connectors.
After rotation, update every Alchemy endpoint and curl script — old secrets stop working immediately.

Note: POST /api/v1/track uses your app tracking key (wg_live_…), not the ingest secret.
Optional for browser/SDK integrations — on-chain operators use the setup wizard + ingest routes above.

# EVM contract templates

First-time setup: use Dashboard → /dashboard/setup (templates pre-selected by market type).

Advanced manual config: Settings → Advanced connectors → EVM → Contract template.

| Template | Use when |
|----------|----------|
| generic_erc20_wager | Custom casino contracts with Trade / Deposit / Settle events |
| polymarket_style | Single-contract Polymarket-style decode (legacy) |
| polymarket_full | Production Polymarket — CTF Exchange + USDC + optional NegRisk |

Advanced fields (trade/deposit/settle event sigs, arg indices) are pre-filled per
template. Override only when your ABI differs.

Player IDs are always stored as {chainId}:0xWallet (e.g. 137:0x742d…).

# Polymarket on Polygon (polymarket_full)

1. Settings → Connectors → EVM → select "Polymarket full (multi-contract)"
2. Paste contract addresses (verify on Polygonscan before production):

   CTF Exchange (primary — OrderFilled trades/settles):
     0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E

   USDC (deposit_completed via Transfer):
     0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174

   NegRisk adapter (optional — same OrderFilled sig):
     paste your deployment address or leave blank

3. Alchemy / QuickNode webhook:
   - Register ALL watched addresses (Exchange + USDC + NegRisk if used)
   - Webhook URL: POST …/api/v1/ingest/{tenantId}/evm
   - Header: Authorization: Bearer <ingest_secret>
   - Prefer GRAPHQL / custom log webhooks that include transaction logs

4. Wagerly decodes:
   - OrderFilled on Exchange/NegRisk → wager_placed / wager_settled
   - USDC Transfer to player wallet → deposit_completed
   - Same wallet maps to player_id 137:0x… across contracts

# Solana ingest

URL:
  POST https://wagerly.tech/api/v1/ingest/{tenantId}/solana
  Authorization: Bearer <ingest_secret>

Player ID format:
  solana:{base58Pubkey}

Settings → Connectors → Solana:
  - Program ID (your Anchor wager program)
  - Template: generic_wager (WagerPlaced / WagerSettled discriminators)
  - Optional Helius webhook secret → verifies x-helius-signature

Helius enhanced webhooks: point at the URL above with the ingest secret header.
Raw transaction JSON (logs array) is also supported when you POST manually.

# Operator tools (dashboard)

Compliance export (Settings → Compliance export)
  CSV download of trigger_fires + RG intervention rows for a date range.
  Use for operator audits and regulator requests.

Credential history (Settings → Credential history)
  Last 10 rotations of ingest_secret, API key, and webhook signing secret.
  Secret values are never stored — only type, timestamp, and actor label.

Data health (Dashboard → Players → Data health)
  Scan for duplicate wallet profiles (e.g. bare 0x vs 137:0x…) after migrating
  to canonical player IDs. Merge reassigns events and aggregates stats.

Vertical presets (Settings → Platform vertical)
  Changing vertical updates trigger threshold hints. After save, choose
  "Apply presets" to rewrite seeded trigger thresholds (Loss streak, Dormancy, Tilt).

curl -X POST https://wagerly.dev/api/v1/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wg_live_your_key" \
  -d '{
    "player_id": "user_123",
    "event": "wager_placed",
    "client_timestamp": "2026-06-23T14:00:00Z",
    "properties": {
      "wager_id": "bet_001",
      "market":   "moneyline",
      "handle":    50,
      "odds":      1.91,
      "currency": "USD"
    }
  }'

# Response: {"ok": true}