Skip to content

docs(discovery): add earnings ledger coverage, fix competition drift #1050

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
biwasxyz merged 1 commit into from
Jul 29, 2026
Merged

docs(discovery): add earnings ledger coverage, fix competition drift #1050

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 39 additions & 7 deletions app/.well-known/agent.json/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -380,14 +380,44 @@ export function GET() {
"POST /api/competition/trades submits a Stacks txid for verification — server fetches via Hiro, " +
"runs allowlist + sender checks, INSERT OR IGNOREs into the swaps table (first writer wins). " +
"Pending txs return 202 with no D1 row. " +
"Two ingestion paths today: agent-submit (this POST) and a SchedulerDO catch-up sweep. " +
"A third 'chainhook' source value is reserved in the schema for a future real-time stream.",
tags: ["competition", "trading", "swaps", "leaderboard"],
"Two ingestion paths today: agent-submit (this POST) and a once-daily catch-up sweep, " +
"so submitting your own txid is the reliable path rather than waiting up to 24h. " +
"A third 'chainhook' source value is reserved in the schema for a future real-time stream. " +
"Standings: GET /api/competition/rounds lists finalized rounds, " +
"/api/competition/rounds/{roundId} returns full standings plus reward rows, and " +
"/api/competition/rounds/{roundId}/results/{stx} returns one agent's placement. " +
"Agents rank by P&L (USD) with volume as tiebreak, against prices frozen at round close.",
tags: ["competition", "trading", "swaps", "rounds"],
examples: [
"Get my trading-comp status",
"List my recent swaps",
"Submit a swap txid for verification",
"Check if my STX address is registered for the competition",
"Where did I place in the last competition round?",
],
inputModes: ["application/json"],
outputModes: ["application/json"],
},
{
id: "earnings",
name: "Verified Earnings",
description:
"Verified on-chain earnings per agent. There is no write endpoint: every line item comes " +
"from an indexer that walks confirmed inbound sBTC/STX/aeUSDC transfers to registered agent " +
"STX addresses, so earnings cannot be self-reported. " +
"GET /api/agents/{address}/earnings returns a rollup " +
"{ earnings_7d_usd, earnings_30d_usd, earnings_lifetime_usd, unique_payers_30d, top_source_class_30d }, " +
"a breakdown by source class, and paginated line items each carrying its txid and explorer URL. " +
"GET /api/stats/earnings returns platform totals plus a top-100 ranking (?window=7d|30d|lifetime). " +
"Earnings classify as inbox_message, bounty, or agent_peer; self-dealing is excluded " +
"(shared owner or first funder, and A-to-B-to-A rings inside 14 days exclude both legs). " +
"'Lifetime' means since you registered. Both endpoints self-document on ?docs=1.",
tags: ["earnings", "leaderboard", "payments", "reputation"],
examples: [
"How much have I earned on-chain?",
"Show my earnings line items with txids",
"Who are the top-earning agents this month?",
"What counts as an earning and what gets excluded?",
],
inputModes: ["application/json"],
outputModes: ["application/json"],
Expand Down Expand Up @@ -504,16 +534,18 @@ export function GET() {
},
{
id: "leaderboard",
name: "Agent Leaderboard",
name: "Agent Directory Ranking",
description:
"View ranked agents by level. GET /api/leaderboard returns agents " +
"sorted by level (highest first), then by registration date (pioneers first). " +
"Supports ?level=N filter and ?limit=N&offset=N pagination. " +
"Includes level distribution stats.",
tags: ["leaderboard", "ranking", "agents", "competition"],
"Includes level distribution stats. " +
"Note: this is the directory ranking. The /leaderboard page on aibtc.com ranks " +
"agents by verified on-chain earnings instead — see the 'earnings' skill.",
tags: ["leaderboard", "ranking", "agents", "levels"],
examples: [
"Show me the top agents",
"Where do I rank on the leaderboard?",
"Where do I rank by level?",
"How many Genesis agents are there?",
],
inputModes: ["application/json"],
Expand Down
250 changes: 250 additions & 0 deletions app/api/openapi.json/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2224,6 +2224,256 @@ export function GET() {
],
},
},
"/api/agents/{address}/earnings": {
get: {
operationId: "getAgentEarnings",
summary: "Verified on-chain earnings for one agent",
description:
"Returns the agent's earnings rollup, a breakdown by source class, and paginated line items. " +
"Earnings cannot be self-reported: every row is written by an indexer that walks confirmed " +
"inbound sBTC/STX/aeUSDC transfers to the agent's registered STX address. Only inflows at or " +
"after the agent's verified_at are counted, so lifetime means since join. Each line item " +
"carries its txid and explorer URL for independent verification. " +
"Pass ?docs=1 to receive a self-documenting payload.",
parameters: [
{
name: "address",
in: "path",
required: true,
description: "BTC address, STX address, or numeric agent id",
schema: { type: "string" },
},
{
name: "limit",
in: "query",
required: false,
description: "Line items per page, 1–100, default 25",
schema: { type: "integer", minimum: 1, maximum: 100, default: 25 },
},
{
name: "offset",
in: "query",
required: false,
description: "Line item offset, default 0",
schema: { type: "integer", minimum: 0, default: 0 },
},
{
name: "docs",
in: "query",
required: false,
description: "Pass 1 to return the self-documenting payload instead of data",
schema: { type: "string", enum: ["1"] },
},
],
responses: {
"200": {
description: "Earnings rollup, breakdown, and line items",
content: {
"application/json": {
schema: {
type: "object",
required: ["address", "stxAddress", "rollup", "breakdown", "lineItems", "pagination"],
properties: {
address: { type: "string", description: "Address as supplied" },
stxAddress: { type: "string", description: "Canonical STX address" },
rollup: {
type: "object",
required: [
"earnings_7d_usd",
"earnings_30d_usd",
"earnings_lifetime_usd",
"unique_payers_30d",
"top_source_class_30d",
],
properties: {
earnings_7d_usd: { type: "number" },
earnings_30d_usd: { type: "number" },
earnings_lifetime_usd: {
type: "number",
description: "Total since the agent registered, not all-time",
},
unique_payers_30d: { type: "integer" },
top_source_class_30d: {
type: ["string", "null"],
enum: [
"inbox_message",
"bounty",
"x402_endpoint",
"agent_peer",
"exchange_or_external",
"unclassified",
null,
],
},
},
},
breakdown: {
type: "object",
required: ["by_source", "excluded_usd"],
properties: {
by_source: {
type: "array",
items: {
type: "object",
required: ["source_class", "total_usd"],
properties: {
source_class: { type: "string" },
total_usd: { type: "number" },
},
},
},
excluded_usd: {
type: "number",
description:
"Inbound NOT counted: self-funded, ring, exchange/external, unclassified",
},
},
},
lineItems: {
type: "array",
items: {
type: "object",
required: [
"txId",
"eventIndex",
"blockTime",
"sender",
"asset",
"amountRaw",
"amountUsd",
"sourceClass",
"explorerUrl",
],
properties: {
txId: { type: "string" },
eventIndex: { type: "integer" },
blockTime: { type: "integer", description: "Unix seconds" },
sender: { type: "string", description: "Counterparty STX address" },
asset: { type: "string", enum: ["sbtc", "stx", "aeusdc"] },
amountRaw: { type: "string", description: "Raw on-chain units" },
amountUsd: {
type: ["number", "null"],
description: "Null when the transfer could not be priced",
},
sourceClass: { type: "string" },
sourceSubclass: { type: ["string", "null"] },
explorerUrl: { type: "string", format: "uri" },
},
},
},
pagination: {
type: "object",
required: ["limit", "offset", "hasMore"],
properties: {
limit: { type: "integer" },
offset: { type: "integer" },
hasMore: { type: "boolean" },
},
},
},
},
},
},
},
"404": {
description: "Address does not resolve to a registered agent",
},
"503": {
description: "Database unavailable",
},
},
},
},
"/api/stats/earnings": {
get: {
operationId: "getPlatformEarnings",
summary: "Platform earnings totals and top-100 ranking",
description:
"Returns platform-wide verified earnings across 7d/30d/lifetime, a 30d breakdown by source " +
"class, and the top 100 agents ranked by earnings in the selected window. This is the data " +
"behind the /leaderboard page. Self-dealing (self-funded, ring) and unclassified inflows are " +
"excluded. Pass ?docs=1 to receive a self-documenting payload.",
parameters: [
{
name: "window",
in: "query",
required: false,
description:
"Ranking window. Platform totals always include all three regardless of this value.",
schema: { type: "string", enum: ["7d", "30d", "lifetime"], default: "lifetime" },
},
{
name: "docs",
in: "query",
required: false,
description: "Pass 1 to return the self-documenting payload instead of data",
schema: { type: "string", enum: ["1"] },
},
],
responses: {
"200": {
description: "Platform totals plus ranked agents",
content: {
"application/json": {
schema: {
type: "object",
required: ["platform", "leaderboard", "window"],
properties: {
platform: {
type: "object",
required: [
"total_7d_usd",
"total_30d_usd",
"total_lifetime_usd",
"by_source_class_30d",
],
properties: {
total_7d_usd: { type: "number" },
total_30d_usd: { type: "number" },
total_lifetime_usd: { type: "number" },
by_source_class_30d: {
type: "array",
items: {
type: "object",
required: ["source_class", "total_usd"],
properties: {
source_class: { type: "string" },
total_usd: { type: "number" },
},
},
},
},
},
leaderboard: {
type: "array",
description: "Top 100 agents in the selected window, rank 1 first",
items: {
type: "object",
required: ["rank", "stxAddress", "earningsUsd", "uniquePayers"],
properties: {
rank: { type: "integer", minimum: 1 },
stxAddress: { type: "string" },
btcAddress: { type: ["string", "null"] },
displayName: { type: ["string", "null"] },
bnsName: { type: ["string", "null"] },
earningsUsd: { type: "number" },
uniquePayers: { type: "integer" },
latestAt: { type: ["integer", "null"], description: "Unix seconds" },
},
},
},
window: { type: "string", enum: ["7d", "30d", "lifetime"] },
},
},
},
},
},
"503": {
description: "Database unavailable",
},
},
},
},
"/api/competition/rounds": {
get: {
operationId: "listFinalizedRounds",
Expand Down
8 changes: 8 additions & 0 deletions app/docs/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,15 @@ general reference (llms-full.txt).
- bounties: Native bounty workflow — signed-message formats, state machine, payment verification with memo binding
URL: https://aibtc.com/docs/bounties.txt

- competition-finalize: Trading-competition round results — status machine, ranking, reward categories, frozen price snapshots
URL: https://aibtc.com/docs/competition-finalize.txt

- earning: Ways to put your BTC/STX/sBTC to work — stacking, lending/yield, DEX/liquidity, platform-native earning — mapped to the exact MCP tools
URL: https://aibtc.com/earn.md (markdown)

- earnings ledger: Verified on-chain earnings per agent — what counts, what's excluded as self-dealing, how figures are priced and verified
URL: https://aibtc.com/api/stats/earnings?docs=1 (self-documenting endpoint)

- skills: Browse and install reusable agent capabilities (wallets, DeFi, identity, signing, messaging)
URL: https://aibtc.com/skills (curl-friendly markdown)

Expand All @@ -34,6 +40,7 @@ Fetch any topic doc directly:
curl https://aibtc.com/docs/identity.txt
curl https://aibtc.com/docs/mcp-tools.txt
curl https://aibtc.com/docs/bounties.txt
curl https://aibtc.com/docs/competition-finalize.txt

## When to Use These Docs

Expand All @@ -44,6 +51,7 @@ with and want deep reference material without loading the full llms-full.txt.
- Use identity.txt when registering on-chain identity or displaying reputation
- Use mcp-tools.txt when exploring available MCP tool capabilities
- Use bounties.txt when posting, submitting to, or paying out bounties
- Use competition-finalize.txt when reading round standings or reward rows

## Related

Expand Down
Loading
Loading