Convexly Public API

v1

The Convexly REST API exposes current evidence surfaces for wallet ratings, Market Trust snapshots, and public track-record summaries. The Decisions API is a legacy surface inherited from an earlier product hypothesis and is in deprecation.

Current

Edge Score API

Jump to reference. Compute the V3b composite from features or end-to-end from a Polymarket wallet address. Auth: Supabase JWT.

https://www.convexly.app/api/engine/edge-score

Current

Market Trust API

Jump to reference. Public v0.1 market-quality cards with evidence counts, caveats, row hashes, links to full card payloads, plus a candidate preview endpoint for canary cards.

/api/market-trust · /api/market-trust/v0.2

Current

Track Record Summary

Jump to reference. Public aggregate status for wallet ratings, Coherence Signals, Market Trust coverage, and caveat language.

https://www.convexly.app/api/track-record/summary

Deprecated

Decisions / Outcomes / Insights API

Legacy surface from the pre-pivot decision-tracking product. Sunsetting 2026-07-29. New integrations should use the Edge Score API. Existing callers will receive a 60-day deprecation notice before removal.

https://www.convexly.app/api/engine/public

The public engine hostname is the same-origin proxy at https://www.convexly.app/api/engine. The old dedicated API subdomain is not published; do not use it in new integrations.

Authentication

Current · Edge Score API

Uses your Supabase access token (JWT) via the Authorization: Bearer <token> header. NOT the same auth as the legacy Decisions API below; the Edge Score routes do NOT accept X-API-Key. Sign in at convexly.app/login to obtain a session token (or use the Supabase client library with your project credentials). Plan-gated to Researcher and above.

curl -H "Authorization: Bearer <supabase_jwt>" \
  https://www.convexly.app/api/engine/edge-score/from-wallet \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0x..."}'

Legacy · Decisions API (X-API-Key)

The decisions API at /api/v1/public/decisions uses X-API-Key header authentication. Generate keys from Settings → API Keys (Researcher tier or higher: Researcher $99/mo, Trader $499/mo, Pro grandfathered, Team $49/seat, or Enterprise custom). This API is in maintenance mode; new integrations should use the Edge Score API above.

curl -H "X-API-Key: cvx_your_api_key_here" \
  https://www.convexly.app/api/engine/public/decisions

Keep your credentials secret. Both Supabase JWTs and X-API-Keys grant access to data scoped to your account. If a credential is compromised, rotate it immediately (sign out + back in for JWT; revoke + regenerate for X-API-Key).

Edge Score

The Edge Score API exposes the V3b composite (posture + conviction + discipline) to external callers. The full methodology is published at Edge Score Methodology V1. Two endpoints: compute from precomputed features, or compute end-to-end from a Polymarket wallet address.

Base URL: https://www.convexly.app/api/engine/edge-score

Authentication: Supabase access token (JWT) via Authorization: Bearer <token>. This is NOT the same auth surface as the public decisions API above; the Edge Score API does not accept X-API-Key. Sign in via the Convexly frontend to obtain a session token, or use the Supabase client library with your project credentials.

Versioning: every response carries version: "v3b". A future composite (V4, etc.) will be served under a new version string with deprecation notice to all active callers.

POST/edge-score/from-features

Compute Edge Score from precomputed features. Rate limit: 60 requests / minute / IP.

Request Body

{
  "skill_brier": 0.05,      // null triggers median imputation
  "concentration": 0.6,     // 0-5, null triggers median imputation
  "n_positions": 40         // required, >= 0
}

Response (200)

{
  "edge_score": 72.4,                     // 0-100 percentile
  "label": "Strong",
  "tagline": "Above average on the composite...",
  "risk_flag": false,
  "breakdown": {
    "edge_score": 72.4,
    "posture_percentile": 65.1,
    "conviction_percentile": 78.3,
    "discipline_percentile": 71.0,
    "posture_contribution": 0.47,
    "conviction_contribution": 2.12,
    "discipline_contribution": -0.28,
    "raw_score": 2.31,
    "n_positions_used": 40,
    "used_median_skill": false,
    "used_median_concentration": false,
    "calibration_percentile": 65.1,       // deprecated alias
    "calibration_contribution": 0.47      // deprecated alias
  },
  "version": "v3b"
}
POST/edge-score/from-wallet

End-to-end: pulls up to 2000 recent trades from the public Polymarket Data API, resolves outcomes, computes features, runs V3b. Cached for 24 hours per wallet. Rate limit: 10 requests / minute / IP.

Request Body

{
  "wallet_address": "0x56687bf447db6ffa42ffe2204a05edaa20f55839"
}

Response (200)

{
  "edge_score": 91.2,
  "label": "Elite",
  "tagline": "Top decile by composite score...",
  "risk_flag": true,
  "breakdown": { ... },                   // same shape as /from-features
  "version": "v3b",
  "wallet_address": "0x0000000000000000000000000000000000000000",
  "n_trades": 1843
}

Errors

401 Missing or invalid JWT

422 Invalid wallet address format

429 Rate limit exceeded; retry after the Retry-After header

502 Polymarket upstream temporarily unreachable

Usage metering: every successful and rate-limited call writes one row to our internal usage log (user ID, route, plan tier, status code, duration, wallet address if applicable). Append-only, user-read-own, service-role write. No metered billing is applied today. Pricing tiers may layer on top in a future release with advance notice.

Backwards compatibility: the calibration_percentile and calibration_contribution fields in the breakdown are deprecated aliases for posture_percentile and posture_contribution (the pillar rename landed 2026-04-18 and is explained in this post). Aliases will be removed in a later major version with at least 60 days of deprecation notice.

Market Trust

The public Market Trust API exposes the same v0.1 daily card artifact used by /market-trust. It is intentionally caveated: pending pillars are listed as pending and unscored, not silently treated as clean evidence. Response-shape version is separate from methodology version:api_versiontracks the envelope; methodology_versiontracks the rating model.

GET/api/market-trust

List public Market Trust card summaries. Optional filters: rating, q, and limit.

curl "https://www.convexly.app/api/market-trust?rating=discount&limit=5"
{
  "schema_version": "market_trust_public_index_v1",
  "api_version": "v1.1",
  "methodology_version": "mtc_v0_1",
  "tier": "public_24h",
  "source_snapshot_date": "20260506",
  "source_snapshot_at_utc": "2026-05-06T00:00:00.000Z",
  "source_snapshot_lag_seconds": 3600,
  "count": 5,
  "returned_count": 5,
  "cards": [
    {
      "condition_id": "0x...",
      "venue": "polymarket",
      "rating": "discount",
      "composite_score": 50,
      "measured_only_composite": {
        "score": 63,
        "n_measured": 3,
        "n_pillars": 7,
        "measured_weight_share": 0.51
      },
      "evidence": { "measured": 3, "heuristic": 3, "pending": 1 },
      "pending_pillars": ["participant_quality"],
      "market_quality_interval": [42, 66],
      "evidence_confidence_score": 48,
      "evidence_confidence_label": "low",
      "verdict_driver": "rating_capped_by_evidence_depth",
      "hard_caps_applied": ["rating_capped_by_evidence_depth"],
      "robustness": {
        "leave_one_pillar_out_range": [44, 57],
        "weight_perturbation_range": [48, 53],
        "verdict_stable_under_sensitivity": true
      },
      "score_waterfall": [{ "key": "coherence", "contribution": 12.2 }],
      "row_hash": "57907a..."
    }
  ]
}

What the math envelope adds

The stable endpoint also surfaces the v0.2 math envelope as non-breaking additions: market_quality_interval, evidence_confidence_score, evidence_confidence_label, verdict_driver, hard_caps_applied, and robustness. These fields expose uncertainty, evidence confidence, rating caps, and sensitivity diagnostics; they do not promote Market Trust to v1. Calibration against the outcome ledger is still the v1 promotion gate. See the methodology contract.

Responses also include X-Convexly-Snapshot-At and X-Convexly-Snapshot-Lag-Seconds headers for freshness monitoring without parsing JSON.

Public snapshot endpoints are CDN-cached and do not emit paid-tier rate-limit headers yet. Authenticated enterprise API keys should add enforced X-RateLimit-* headers when that quota layer ships. Vercel caching uses CDN-Cache-Control and Vercel-CDN-Cache-Control for the 5-minute public snapshot TTL.

GET/api/market-trust/{condition_id}

Return the full public card payload for one condition ID. Polymarket is the only v0.1 venue exposed today.

curl "https://www.convexly.app/api/market-trust/0x...?venue=polymarket"
{
  "schema_version": "market_trust_public_card_v1",
  "api_version": "v1.1",
  "methodology_version": "mtc_v0_1",
  "audit_artifact_id": "57907a...",
  "source_snapshot_at_utc": "2026-05-06T00:00:00.000Z",
  "source_snapshot_lag_seconds": 3600,
  "contract_status": "stable_legacy_snapshot",
  "market_quality_interval": [42, 66],
  "evidence_confidence_score": 48,
  "evidence_confidence_label": "low",
  "verdict_driver": "rating_capped_by_evidence_depth",
  "hard_caps_applied": ["rating_capped_by_evidence_depth"],
  "robustness": {
    "leave_one_pillar_out_range": [44, 57],
    "weight_perturbation_range": [48, 53],
    "verdict_stable_under_sensitivity": true
  },
  "measured_only_composite": { "score": 63, "n_measured": 3 },
  "score_waterfall": [],
  "card": { "...": "full public card" }
}
GET/api/market-trust/v0.2Preview

List current candidate Market Trust cards. This is a canary evidence surface, not the stable public methodology, and should be labeled as preview in any buyer-facing integration.

curl "https://www.convexly.app/api/market-trust/v0.2?venue=polymarket&limit=5"
{
  "schema_version": "market_trust_v0_2_preview_index_v1",
  "api_version": "v1.2-preview",
  "methodology_version": "mtc_v0_2_candidate",
  "contract_status": "canary_preview",
  "stable_contract_url": "/api/market-trust",
  "promotion_gate": "freshness_coverage_outcome_history",
  "promotion_blockers": [
    "v1_candidate_requires_resolved_outcome_ledger_row"
  ],
  "tier": "experimental_v0_2_preview",
  "source_snapshot_at_utc": "2026-05-08T10:20:12.000Z",
  "source_snapshot_lag_seconds": 480,
  "caveats": [
    "Candidate diagnostic scorecard, not investment advice or certification.",
    "Participant-quality is measured only when identity, data-rights, and coverage gates pass."
  ],
  "cards": [
    {
      "condition_id": "0x...",
      "venue": "polymarket",
      "rating": "use_with_caveats",
      "score": 68,
      "market_quality_score": 68,
      "market_quality_interval": [55, 76],
      "evidence_confidence_score": 62,
      "evidence_confidence_label": "medium",
      "verdict_driver": "rating_capped_by_quality_interval_low",
      "hard_caps_applied": [
        "cap_use_until_outcome_history_matures"
      ],
      "promotion_blockers": [
        "v1_candidate_requires_resolved_outcome_ledger_row"
      ],
      "robustness": {
        "verdict_stable_under_sensitivity": false,
        "leave_one_pillar_out_range": [51, 72],
        "weight_perturbation_range": [64, 70]
      },
      "evidence_counts": {
        "measured": 4,
        "heuristic": 2,
        "pending": 1,
        "blocked_data_rights": 0
      },
      "source_snapshot_lag_seconds": 480,
      "audit_artifact_id": "d3b0..."
    }
  ]
}

The detail endpoint is /api/market-trust/v0.2/{condition_id}?venue=polymarket. It returns the full candidate card payload, includingaudit_artifact_id, market-quality interval, evidence confidence, robustness diagnostics, promotion blockers, evidence caveats, allowed wording, not-claiming language, and source freshness. Treat this as a canary-preview contract: promote this surface only after freshness coverage and outcome history are strong enough, and the founder approves the public wording gate.

Track Record

The public track-record summary is a compact status endpoint for Convexly's evidence layer. It reports artifact coverage and caveats; it does not claim mature realized performance before resolved outcomes and matched controls support that wording.

GET/api/track-record/summary

Aggregate public status for wallet ratings, Coherence Signals, Market Trust, and evidence caveats.

curl "https://www.convexly.app/api/track-record/summary"
{
  "schema_version": "platform_track_record_summary_v1",
  "methodology_versions": {
    "wallet_ratings": "edge_score_v3b_public_snapshot",
    "coherence_signals": "cme_v0_1",
    "market_trust": "mtc_v0_1_public_snapshot"
  },
  "summary": {
    "walletRatings": { "publicLeaderboardSize": 50 },
    "coherenceSignals": { "signalsEmittedToday": 96 },
    "marketTrust": { "publicCards": 5 }
  }
}

Legacy: Decisions, Outcomes, Insights. The next three sections document the pre-pivot decision-tracking API. Authentication is via X-API-Key, not JWT. This surface is in deprecation and will be removed on 2026-07-29; existing callers receive a 60-day notice before that date. New integrations should use the Edge Score API above.

Decisions

POST/decisions

Create a new decision.

Request Body

{
  "title": "Example decision",       // required, max 200 chars
  "description": "Context for the decision",
  "probability": 0.7,                  // required, 0-1
  "best_case": 5000,                   // best-case outcome value
  "expected_case": 2000,               // expected outcome value
  "worst_case": -1000,                 // worst-case outcome value
  "category": "strategy",               // optional, max 50 chars
  "tags": ["q1", "growth"],            // optional array
  "source": "api"                      // optional, default "api"
}

Response (201)

{
  "decision": {
    "id": "uuid",
    "title": "Example decision",
    "probability": 0.7,
    "status": "active",
    "created_at": "2026-03-07T12:00:00Z",
    ...
  }
}
GET/decisions

List your decisions, newest first.

Query Parameters

limit - Max results (1-100, default 50)

offset - Skip N results (pagination)

Response (200)

{
  "decisions": [ ... ],
  "count": 25
}
GET/decisions/{id}

Get a specific decision with its outcomes.

Response (200)

{
  "decision": {
    "id": "uuid",
    "title": "Example decision",
    "probability": 0.7,
    "outcomes": [ ... ],
    ...
  }
}

Outcomes

POST/decisions/{id}/outcome

Record the outcome of a decision.

Request Body

{
  "result": "success",     // "success", "failure", or descriptive string
  "notes": "Shipped on time, 20% adoption in week 1"
}

Response (201)

{
  "outcome": {
    "id": "uuid",
    "decision_id": "uuid",
    "result": "success",
    "recorded_at": "2026-03-07T12:00:00Z"
  }
}

Insights

GET/insights

Get a behavioral insights summary including Brier score and calibration stats.

Response (200)

{
  "total_decisions": 42,
  "resolved_decisions": 18,
  "average_brier_score": 0.1823,
  "generated_at": "2026-03-07T12:00:00Z"
}

Key Management

Key management endpoints use JWT authentication (your Supabase session), not API keys. These are used by the Settings page to manage keys.

POST/keys

Generate a new API key. The raw key is returned once and cannot be retrieved again.

Request Body

{
  "label": "My Slack integration"   // optional, default "default"
}

Response (201)

{
  "raw_key": "cvx_abc123...",
  "key_id": "uuid",
  "label": "My Slack integration",
  "created_at": "2026-03-07T12:00:00Z",
  "message": "Store this key securely -- it will not be shown again."
}
GET/keys

List your API keys (shows last 4 characters only).

Response (200)

{
  "keys": [
    {
      "id": "uuid",
      "label": "My Slack integration",
      "key_preview": "3xyz",
      "revoked": false,
      "last_used_at": "2026-03-07T10:00:00Z",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}
DELETE/keys/{key_id}

Revoke an API key. The key will immediately stop working.

Response (200)

{
  "revoked": true,
  "key_id": "uuid"
}

Rate Limits & Plan Access

Free

Edge Score API not included. Use the analyzer for one-off scoring.

Researcher · Trader INCLUDED

60 req/min on /from-features, 10 req/min on /from-wallet. Authenticate via Supabase JWT (X-API-Key for the public decisions API). Generate keys from Settings → API Keys.

Custom Enterprise

Higher rate limits, dedicated capacity statement, support windows, and named-cohort benchmarking only when written into an approved pilot or contract. Contact for terms.

Rate-limit headers are included on rate-limited responses: X-RateLimit-Remaining, X-RateLimit-Reset. Free-tier callers receive HTTP 403 with detail.error = "plan_required" and an upgrade_url pointing at /pricing.

Code Examples

Edge Score from a Polymarket wallet

curl -X POST https://www.convexly.app/api/engine/edge-score/from-wallet \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x56687bf447db6ffa42ffe2204a05edaa20f55839"
  }'

Legacy: Decisions API

Create a decision

curl -X POST https://www.convexly.app/api/engine/public/decisions \
  -H "X-API-Key: cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Example decision",
    "probability": 0.65,
    "best_case": 50000,
    "expected_case": 20000,
    "worst_case": -10000,
    "category": "strategy"
  }'

List decisions

curl https://www.convexly.app/api/engine/public/decisions?limit=10 \
  -H "X-API-Key: cvx_your_key"

Record an outcome

curl -X POST https://www.convexly.app/api/engine/public/decisions/{id}/outcome \
  -H "X-API-Key: cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"result": "success", "notes": "Shipped on schedule"}'

Error Responses

401

Missing or invalid API key

404

Decision not found (or doesn't belong to you)

422

Validation error (missing or invalid fields)

429

Rate limit exceeded

502

Upstream database error

Need help? Manage API keys · Go to Dashboard

OpenAPI JSON will return after the dedicated API subdomain is configured; current working examples use the same-origin engine proxy above.