GET /v1/points/me

Return the points balance and recent events for the authenticated API key.

Points accrue from real product use — trading on swap.venum.dev, calling the API, hitting the RPC gateway, signing up. The balance is computed from an immutable event ledger that the points reconciler updates every few minutes from the source-of-truth tables (swap_landed, api_key_endpoint_usage). totalPoints is clamped at 0 (you'll never see a negative balance), but breakdown.apiUsage stays signed so you can see when rate-limit hits are eating into your earnings.

Request

GET /v1/points/me
x-api-key: YOUR_API_KEY

Example

curl https://api.venum.dev/v1/points/me \
  -H 'x-api-key: YOUR_API_KEY'

Response

200 OK

{
  "apiKeyId": 1234,
  "tier": "free",
  "totalPoints": 1287.42,
  "breakdown": {
    "apiUsage": 137.42,
    "signup": 50,
    "referral": 1100,
    "wallet": 0
  },
  "referral": {
    "code": "a1b2c3d4",
    "referrerApiKeyId": null,
    "referralCount": 7
  },
  "recentEvents": [
    {
      "id": 904,
      "kind": "api_usage",
      "points": 12.5,
      "sourceId": "usage:1234:1715000000",
      "meta": {
        "tier": "free",
        "rawDelta": 12.5,
        "capped": false,
        "dailyCap": 100,
        "multiplier": 5,
        "phase": "genesis",
        "apiSuccessful": 1234,
        "rpcSuccessful": 0,
        "rateLimited": 1
      },
      "createdAt": "2026-05-06T15:34:00.000Z"
    }
  ]
}

Fields

Field	Type	Description
apiKeyId	number	Internal id of the authenticated key.
tier	string	"free" | "starter" | "pro".
totalPoints	number	Sum across all breakdown buckets. Clamped at 0 — you never see a negative balance.
breakdown.apiUsage	number	Net of API + RPC + rate-limit deductions. Signed — can go negative when rate-limit hits exceed earnings (e.g. -0.53); shown that way deliberately so you can see your usage pattern is hurting your score.
breakdown.signup	number	One-time signup credit. Credit-only.
breakdown.referral	number	Sum of credits from this account's referrals. Credit-only.
breakdown.wallet	number	Sum of swap-derived points (currently always 0; activates once wallet linkage ships).

Worked example

You signed up (+10) and then hammered the rate limit, accruing -0.53 in deductions:

{
  "totalPoints": 9.47,
  "breakdown": { "apiUsage": -0.53, "signup": 10, "referral": 0, "wallet": 0 }
}

totalPoints is signup + apiUsage = 10 - 0.53 = 9.47. Sustained rate-limit abuse can push the raw signed sum negative, in which case totalPoints floors at 0 but apiUsage keeps showing the real (negative) deduction. | referral.code | string | Share with friends as venum.dev/r/<code> to credit referrals. | | referral.referrerApiKeyId | number | null | The api_key that referred this account, if any. | | referral.referralCount | number | Number of accounts that signed up using this account's referral code. | | recentEvents | array | Up to 25 most-recent ledger events for this api_key, newest first. Each event carries kind, points, sourceId, meta, createdAt. |

Errors

Status	Description
401	Missing or invalid API key.
404	API key has no points record yet (rare — every key gets a signup event on the first reconcile pass).

Staleness

The reconciler runs every ~5 minutes. A request that just landed a swap or hit the API may take up to that long to appear in the balance.

Rate Limit

See Plans & Rate Limits.

Notes

• There is no public wallet lookup endpoint. Querying arbitrary wallet balances would dox whales and ease sybil reconnaissance.
• The full earning rules — what counts, what doesn't, the early-bird curve, the daily ceilings — are summarised at venum.dev/earn.
• Points are not a contractual promise of token allocation. Final allocation rules are set per snapshot and published in advance.