Reporting endpoints

Partners can query their own account, usage, and rebate data with the same X-ORKID-API-Key header. All responses are scoped to the account that owns the key — a key can never see another partner's data.

Sandbox note: These endpoints return empty/zero results on the sandbox because sandbox traffic is not tracked.

GET /api/v1/account

Returns the partner account, including the configured rebate rate.

curl -H "X-ORKID-API-Key: <key>" https://orkidlabs.xyz/api/v1/account

{
  "ok": true,
  "account": {
    "id": "...",
    "slug": "alternatefutures",
    "name": "Alternate Futures",
    "rebate_bps": 3,
    "rebate_active": true
  }
}

GET /api/v1/usage

Lists usage events (quotes and solves) recorded for the account.

Optional filters:

Parameter	Description
`?period=YYYY-MM`	Filter by month
`?event_type=route\|solve`	Filter by event type
`?limit=N`	Limit results (default 100)

curl -H "X-ORKID-API-Key: <key>" "https://orkidlabs.xyz/api/v1/usage?event_type=solve&period=2026-09"

{
  "ok": true,
  "events": [
    {
      "event_type": "solve",
      "volume_usd": 25,
      "is_dry_run": true,
      "created_at": "..."
    }
  ],
  "total_volume_usd": 25
}

Event flags

Each event carries:

is_dry_run — encode-only, not executed
is_test — operator-marked test traffic

Only is_dry_run=false, is_test=false solve events count toward rebates.

GET /api/v1/rebates

Lists monthly rebate ledger entries. Optional filter: ?period=YYYY-MM.

curl -H "X-ORKID-API-Key: <key>" "https://orkidlabs.xyz/api/v1/rebates?period=2026-09"

{
  "ok": true,
  "rebates": [
    {
      "period": "monthly",
      "period_start": "2026-09-01T00:00:00+00:00",
      "volume_usd": 100,
      "rebate_bps": 3,
      "rebate_usd": 0.03,
      "status": "accrued"
    }
  ]
}

Rebate volume counts only non-dry-run, non-test solve events. rebate_usd = volume_usd * rebate_bps / 10,000. Entries move from accrued to paid when Orkid settles monthly.

Referral rebates

Partners who source other partners earn a referral cut of the referred account's volume. Referral income appears as separate ledger rows:

{
  "kind": "referral",
  "source_account_id": "<referred-account-uuid>",
  "volume_usd": 1000,
  "rebate_bps": 1,
  "rebate_usd": 0.10
}

kind: "volume" rows are your own volume; kind: "referral" rows pay you for a referred partner's volume.

POST /api/v1/confirm

For user-pays-gas swaps (below the gasless minimum), the client must confirm the transaction after it's mined so the volume is tracked.

curl -X POST https://orkidlabs.xyz/api/v1/confirm \
  -H "X-ORKID-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"txHash": "0x...", "chain": "base"}'

The API verifies on-chain that the transaction succeeded, targeted the TVMExecutor, and matches the exact calldata it encoded (keccak256 of tx.input). Self-reported hashes that don't match an encoded swap are rejected.

The SDK (client.confirmTransaction), CLI (orkid confirm <txHash>), and widget call this automatically. Hand-rolled integrations must call it explicitly or below-min volume won't be tracked.