openapi: 3.0.3 info: title: Tereno — The Agent Economy API version: 3.0.0 description: | Tereno is an economy where agents turn knowledge into capital. Every endpoint is a move in that economy, not just an integration: lookups map demand and publish the economics of a decision; paid acquisitions settle via x402 below the measured reproduction cost, compound the wallet's standing (a permanent price curve), and — for the first wallet ever to pay for an answer — record sponsorship provenance that pays a royalty on every reuse. Standing, credits and provenance are non-portable capital tied to the wallet. The current phase runs in TERENO_MARKET_MODE=consume_only: production is concentrated in the network itself and no external payout is enqueued; open third-party production (80/5/15 USDC splits) is a later, demand-gated phase. servers: - url: https://tereno.xyz description: Production - url: http://localhost:3000 description: Local development paths: /api/v1/discoveries/lookup: get: summary: Free lookup — the economics of the decision description: | The free opening move. Returns the full economics for (type, subject) without scanning RPC. An EIP-712-signed lookup is eligible to affect standing and receives wallet-specific tier/credit pricing reserved in a single-use quote. An unsigned lookup remains available at public list price and is stored only as raw demand. A miss returns producible:true with a paid JIT production URL — being first to pay it makes you the asset's sponsor. parameters: - name: type in: query required: true schema: type: string enum: [smart_money, wallet_reputation, whale_classification] - name: subject in: query required: true description: EVM address the discovery is about. schema: type: string example: "0x4ed4e862860bed51a9570b96d89af5e1b0efefed" - name: wallet in: query required: true description: Consumer wallet used for a frozen quote; the paid signer must match it. schema: type: string - name: x-agent-wallet in: header required: false description: EVM signer. Supply all four x-agent-* headers to authenticate the lookup. schema: type: string - name: x-agent-signature in: header required: false description: EIP-712 AgentAction signature for action=lookup and resource=type:normalizedSubject. schema: type: string - name: x-agent-timestamp in: header required: false description: Unix timestamp in milliseconds, within five minutes. schema: type: string - name: x-agent-nonce in: header required: false description: Unique 8-128 character nonce; replays are rejected. schema: type: string responses: '200': description: Lookup result and economics. content: application/json: schema: $ref: '#/components/schemas/LookupResponse' '400': description: Invalid type or subject. /api/v1/discoveries/produce: get: summary: Acquire a knowledge asset via x402 — and possibly own it description: | The capital-forming move, and the Bazaar-listed resource. Call it directly with type, subject and the payer wallet at public list price, or include a fresh demand id from a signed free lookup to preserve its wallet-specific frozen quote. Each demand id can settle only once. On a cache miss, Tereno scans the subject once, derives all three assets, caches them with a TTL and returns the requested payload after settlement — and records the payer as the asset's sponsor. Every later settled reuse by another wallet pays the sponsor a royalty in consumption credits; every settlement compounds the payer's standing. parameters: - name: type in: query required: true schema: type: string enum: [smart_money, wallet_reputation, whale_classification] - name: subject in: query required: true schema: type: string - name: demand in: query required: false description: Optional single-use demandEventId from lookup. Its type, subject, wallet and frozen price must match. schema: type: string - name: wallet in: query required: true description: Must match the wallet that signs the x402 payment. schema: type: string responses: "200": description: Produced or cached payload with pricing and production metadata. headers: PAYMENT-RESPONSE: description: x402 settlement receipt. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PurchasedDiscovery' "402": description: Payment Required using either the frozen lookup quote or the current direct price. "409": description: Supplied quote is invalid, used or expired, or production is already in progress. "429": description: Bounded paid-compute budget exceeded; payment is not settled. "422": description: Subject exceeds bounded scan limits. "502": description: RPC upstream failure; payment is not settled. "504": description: RPC timeout; payment is not settled. /api/v1/discoveries/{id}: get: summary: Buy a discovery payload via x402 description: | Returns HTTP 402 when unpaid. Sign one of the x402 accepts entries and retry with PAYMENT-SIGNATURE. Settlement happens only after a successful response. In consume_only mode, the full payment goes to the platform. parameters: - name: id in: path required: true schema: type: string - name: demand in: query required: false schema: type: string description: demandEventId from lookup, used for buy-rate metrics. - name: wallet in: query required: false schema: type: string - name: PAYMENT-SIGNATURE in: header required: false schema: type: string responses: '200': description: Purchased discovery payload. headers: PAYMENT-RESPONSE: description: x402 settlement receipt. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PurchasedDiscovery' '402': description: Payment Required with dynamic discovery price. '404': description: Discovery not found; payment not settled. '410': description: Discovery expired or invalid; payment not settled. /api/v1/discoveries: get: summary: Browse discovery metadata parameters: - name: type in: query schema: type: string enum: [smart_money, wallet_reputation, whale_classification] - name: subject in: query schema: type: string - name: minReputation in: query schema: type: number responses: '200': description: Metadata only; payload requires x402 purchase. content: application/json: schema: type: object properties: count: type: integer discoveries: type: array items: $ref: '#/components/schemas/DiscoveryMetadata' post: summary: Seed or publish a discovery description: | In consume_only mode this route is for internal platform seeding and requires x-platform-publish-secret. In two_sided mode it accepts external EIP-191 producer signatures. parameters: - name: x-platform-publish-secret in: header required: false schema: type: string - name: x-producer-address in: header required: false schema: type: string - name: x-producer-signature in: header required: false schema: type: string - name: x-producer-timestamp in: header required: false schema: type: string - name: x-producer-nonce in: header required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishRequest' responses: '201': description: Discovery listed. '400': description: Invalid body. '401': description: Invalid producer signature. '403': description: External producer publishing disabled in consume_only mode. '422': description: Rejected by platform spot-check. /api/v1/discoveries/{id}/feedback: post: summary: Submit consumer feedback on a purchased discovery parameters: - name: id in: path required: true schema: type: string - name: x-agent-wallet in: header required: true schema: type: string - name: x-agent-signature in: header required: true description: EIP-712 AgentAction signature for action=feedback and resource=id:accurate|inaccurate. schema: type: string - name: x-agent-timestamp in: header required: true schema: type: string - name: x-agent-nonce in: header required: true schema: type: string requestBody: content: application/json: schema: type: object required: [accurate] properties: accurate: type: boolean responses: '200': description: Feedback recorded. '401': description: Missing, invalid or replayed wallet signature. '403': description: The signed wallet has no settled purchase for this discovery. '409': description: This purchaser already submitted feedback. /api/v1/stats: get: summary: Public economy counters responses: '200': description: Current counters. '429': description: Public read budget exceeded; retry after the response delay. /api/v1/agents/{wallet}/portfolio: get: summary: Read a wallet's accumulated capital description: | Free read of any agent's balance sheet in the economy: standing and tier (the permanent price curve), spendable credit balance, sponsored knowledge assets with their reuse counts and royalty yield, 30-day yield, surplus captured versus reproduction cost, network impact, and the quantified cost of leaving. Everything derives from settled onchain activity; the wallet is the identity, no auth. parameters: - name: wallet in: path required: true description: EVM address of the agent. schema: type: string responses: '200': description: The wallet's portfolio. '400': description: Invalid wallet address. '429': description: Public read budget exceeded; retry after the response delay. components: schemas: LookupResponse: type: object properties: found: type: boolean producible: type: boolean demandEventId: type: string discovery: $ref: '#/components/schemas/DiscoveryMetadata' economics: type: object properties: priceUsd: type: number yourPriceUsd: type: number reproductionCostUsd: type: number buyingIsCheaper: type: boolean estimatedSavingUsd: type: number selfCompute: type: object description: >- Decomposed self-compute benchmark. benchmarkUsd is the declared full cost of self-computing (assumptions documented at /methodology/self-compute.md); marginalRpcUsd is the measured RPC-only cost from recent real scans — the honest lower bound for buyers who already run indexing infrastructure. properties: benchmarkUsd: type: number marginalRpcUsd: type: number nullable: true measuredRpcCalls: type: number nullable: true samples: type: integer unitCostUsd: type: number methodologyUrl: type: string note: type: string buyUrl: type: string DiscoveryMetadata: type: object properties: discoveryId: type: string type: type: string enum: [smart_money, wallet_reputation, whale_classification] subject: type: string producer: type: string description: Platform wallet in consume_only mode. priceUsd: type: number productionCostUsd: type: number ttlSeconds: type: integer publishedAt: type: string format: date-time expiresAt: type: string format: date-time source: type: string enum: [rpc, mock-provider] PurchasedDiscovery: type: object required: [discoveryId, type, subject, payload, producer, publishedAt, expiresAt, purchaseId, consumer, production, pricing, settlementEconomics, payment] properties: discoveryId: type: string type: type: string enum: [smart_money, wallet_reputation, whale_classification] subject: type: string pattern: '^0x[a-fA-F0-9]{40}$' payload: type: object additionalProperties: true producer: type: string publishedAt: type: string format: date-time expiresAt: type: string format: date-time purchaseId: type: string consumer: type: string production: type: object properties: source: type: string productionCostUsd: type: number cacheTtlSeconds: type: integer pricing: type: object properties: listPriceUsd: type: number pricePaidUsd: type: number tierDiscountPct: type: number creditAppliedUsd: type: number description: >- Sponsorship credit consumed by this purchase. pricePaidUsd is always the USDC amount actually settled via x402. sponsorship: type: object description: >- The first settled buyer of a discovery becomes its sponsor and earns non-transferable consumption credits (SPONSOR_ROYALTY_PCT of the price, default 20%) every time another wallet buys it. properties: sponsor: type: string nullable: true youAreSponsor: type: boolean settlementEconomics: type: object properties: mode: type: string enum: [consume_only, two_sided] platformUsd: type: number producerUsd: type: number description: Zero in consume_only mode. incentiveUsd: type: number description: Zero in consume_only mode. payment: type: string enum: [settlement_pending_response_hook, simulated_settled] PublishRequest: type: object required: [type, subject, payload, priceUsd, productionCostUsd, ttlSeconds] properties: type: type: string enum: [smart_money, wallet_reputation, whale_classification] subject: type: string payload: type: object priceUsd: type: number minimum: 0.001 productionCostUsd: type: number ttlSeconds: type: integer source: type: string enum: [rpc, mock-provider]