Stats endpoints

Aggregate swap volume reporting. The Venum swap dApp records every landed swap to a Postgres-backed swap_landed table; the public /v1/stats/volume endpoint serves the rolling totals (USD volume, swap count) for any time window directly from that table.

These endpoints power the Venum DefiLlama dimension-adapter listing and any third-party analytics that wants to show our aggregator volume.

---

POST /v1/stats/swap-landed

Record a successful on-chain swap. Called by frontends after polling /v1/tx/:signature and observing a confirmed or finalized status.

The server resolves the input/output mints, computes a USD value snapshot from the current pool prices (same source as /v1/prices), dedupes by signature, and inserts a row into the swap_landed Postgres table (ON CONFLICT (signature) DO NOTHING).

Request

POST /v1/stats/swap-landed
Content-Type: application/json
X-API-Key: YOUR_API_KEY

Body

Field	Type	Required	Description
inputMint	string	Yes	Base58 mint or token symbol
outputMint	string	Yes	Base58 mint or token symbol
inputAmount	string	Yes	Raw amount sent in (smallest units)
outputAmount	string	Yes	Raw amount received (smallest units)
signature	string	Yes	Base58 transaction signature (80–90 char)
dex	string	No	DEX identifier (e.g. orca-whirlpool)
poolAddress	string	No	Base58 pool address

Example

curl -X POST https://api.venum.dev/v1/stats/swap-landed \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "inputMint": "SOL",
    "outputMint": "USDC",
    "inputAmount": "1000000000",
    "outputAmount": "168200000",
    "signature": "5j7Sc...Wxyz",
    "dex": "orca-whirlpool",
    "poolAddress": "HJPjoWUrhoZzkNfRpHuieeFk9AnbVjTk9Gc5SJRqsQTK"
  }'

Response

{ "status": "recorded", "signature": "5j7Sc...Wxyz" }

If the signature has already been recorded:

{ "status": "already-recorded", "signature": "5j7Sc...Wxyz" }

status values:

• recorded — the row was inserted
• already-recorded — the signature already existed (idempotent)
• accepted-no-db — the API is running without a Postgres connection (dev/standalone). The call is accepted so frontends don't error, but nothing is persisted.

Errors

Status	Description
400	Invalid request body or unknown symbol
401	Missing or invalid API key
429	Rate limit exceeded
500	Failed to persist swap record (Postgres error)

Auth

Requires API key.

---

GET /v1/stats/volume

Return total USD swap volume and swap count for a time window.

Request

GET /v1/stats/volume?from=<unix>&to=<unix>

Query parameters

Field	Type	Required	Default	Description
from	number	No	0	Window start, UNIX seconds (inclusive)
to	number	No	now	Window end, UNIX seconds (exclusive)

Example

# Last 24h
NOW=$(date -u +%s)
DAY_AGO=$((NOW - 86400))
curl "https://api.venum.dev/v1/stats/volume?from=$DAY_AGO&to=$NOW"

Response

{
  "from": 1733500800,
  "to": 1733587200,
  "volumeUsd": 124530.42,
  "swapCount": 87
}

volumeUsd is the sum of the larger of input/output USD value for each swap in the window — defensive against any one side being temporarily unpriced. swapCount counts the number of recorded landed swaps in the window.

Errors

Status	Description
400	Invalid from / to (non-numeric or from > to)
429	Rate limit exceeded
500	Failed to query the swap_landed table

Auth

Optional auth. The endpoint is intended to be queryable by external indexers (e.g. DefiLlama) without an API key.

Rate Limit

Tier limits (per minute):

Tier	Limit
anonymous	30
free	60
starter	300
pro	1000
internal	∞

Cached for 60 s server-side.