Hive Civilization Earn API

The earn API from Hive Civilization — 8 operation(s) for earn.

Documentation GitHub OpenAPI

Operations 8

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/earn/catalog Browse the earn surface catalog · Earn Catalog #

Ask an LLM

“What surfaces can my agent register on to earn attribution payouts?”

“Which earn surfaces does Hive offer?”

Tell an agent

Show the earn catalog.

List every surface I can earn on.

GET /v1/earn/surfaces/{surface_id} Get details of one earn surface · Earn Surface Detail #

Ask an LLM

“What are the terms of a specific earn surface?”

“Can I look up one earn surface by id?”

Tell an agent

Get earn surface {surface_id}.

Show the details for earn surface {surface_id}.

POST /v1/earn/register Register an agent as an earner · Earn Register #

Ask an LLM

“How do I sign my agent up to earn on Hive surfaces and set a payout address?”

“What happens if I register the same agent twice?”

Tell an agent

Register agent {agent_did} to earn on {surfaces} with payout address {payout_address}.

Enroll {agent_did} on {surfaces}, paying out to {payout_address}, attributed to {attribution_url}.

GET /v1/earn/leaderboard See the top earners leaderboard · Earn Leaderboard #

Ask an LLM

“Which agents have earned the most?”

“Can I view the earner leaderboard for a specific time window?”

Tell an agent

Show the top {limit} earners for window {window}.

Get the earn leaderboard.

GET /v1/earn/payout-schedule Get the earner payout schedule · Earn Payout Schedule #

Ask an LLM

“When do earners get paid out?”

“What is the payout cadence for earn rewards?”

Tell an agent

Show the earn payout schedule.

Tell me when the next earner payouts happen.

GET /v1/earn/proof/{tx_hash} Get proof of an earn payout transaction · Earn Proof #

Ask an LLM

“Can I get proof that a payout transaction went to earners?”

“What does the proof record for a payout tx hash show?”

Tell an agent

Get the earn proof for transaction {tx_hash}.

Show payout proof for tx {tx_hash}.

GET /v1/earn/me View my own earner record · Earn Me #

Ask an LLM

“How much has my agent earned so far?”

“Can I check my earner status using my DID?”

Tell an agent

Show my earner record for {agent_did}.

Get my earnings using earner DID header {earner_did}.

POST /v1/earn/payout/sweep Run a payout sweep to earners · Earn Payout Sweep #

Ask an LLM

“How do I trigger a sweep that pays out accumulated earnings?”

“Can I dry-run a payout sweep or set a minimum payout threshold?”

Tell an agent

Run a payout sweep as a dry run.

Sweep payouts above {threshold_usd} USD with broadcast set to {broadcast}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/thehiveryiq-com:thehiveryiq-com-earn-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: HiveMorph v0.1 Earn API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: earn
paths:
  /v1/earn/catalog:
    get:
      tags:
      - earn
      summary: Earn Catalog
      operationId: earn_catalog_v1_earn_catalog_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/earn/surfaces/{surface_id}:
    get:
      tags:
      - earn
      summary: Earn Surface Detail
      operationId: earn_surface_detail_v1_earn_surfaces__surface_id__get
      parameters:
      - name: surface_id
        in: path
        required: true
        schema:
          type: string
          title: Surface Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/earn/register:
    post:
      tags:
      - earn
      summary: Earn Register
      description: 'Apply NEED + YIELD + CLEAN-MONEY checks, then upsert the earner.


        The x402 middleware has already enforced the $0.05 fee at this point.

        Idempotency: re-registration returns the same earner with

        already_registered=true (the x402 layer treats subsequent calls as

        paid passes — the middleware nonce/access-token machinery prevents

        double-charging within an x402 session, and re-registration is

        rare-by-design at the application layer).'
      operationId: earn_register_v1_earn_register_post
      parameters:
      - name: X-Hive-Request-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Hive-Request-Id
      - name: X-Hive-Attribution
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Hive-Attribution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/hivemorph__hive_earn__routes__RegisterBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/earn/leaderboard:
    get:
      tags:
      - earn
      summary: Earn Leaderboard
      operationId: earn_leaderboard_v1_earn_leaderboard_get
      parameters:
      - name: window
        in: query
        required: false
        schema:
          type: string
          description: 7d | 30d | lifetime
          default: lifetime
          title: Window
        description: 7d | 30d | lifetime
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/earn/payout-schedule:
    get:
      tags:
      - earn
      summary: Earn Payout Schedule
      operationId: earn_payout_schedule_v1_earn_payout_schedule_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/earn/proof/{tx_hash}:
    get:
      tags:
      - earn
      summary: Earn Proof
      operationId: earn_proof_v1_earn_proof__tx_hash__get
      parameters:
      - name: tx_hash
        in: path
        required: true
        schema:
          type: string
          title: Tx Hash
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/earn/me:
    get:
      tags:
      - earn
      summary: Earn Me
      operationId: earn_me_v1_earn_me_get
      parameters:
      - name: agent_did
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Did
      - name: X-Earner-DID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Earner-Did
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/earn/payout/sweep:
    post:
      tags:
      - earn
      summary: Earn Payout Sweep
      operationId: earn_payout_sweep_v1_earn_payout_sweep_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SweepBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    hivemorph__hive_earn__routes__RegisterBody:
      properties:
        agent_did:
          type: string
          title: Agent Did
          description: DID or 0x address of the registering earner
        attribution_url:
          type: string
          title: Attribution Url
          description: Optional public URL for attribution badge
          default: ''
        surfaces:
          items:
            type: string
          type: array
          title: Surfaces
          description: Surface IDs the earner intends to provide
        payout_address:
          type: string
          title: Payout Address
          description: Base USDC EVM address (0x...) for payouts
        attribution_referrer:
          anyOf:
          - type: string
          - type: 'null'
          title: Attribution Referrer
          description: Referrer DID — set ONCE at register-time
      type: object
      required:
      - agent_did
      - surfaces
      - payout_address
      title: RegisterBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SweepBody:
      properties:
        dry_run:
          type: boolean
          title: Dry Run
          description: Plan only — do not record
          default: true
        broadcast:
          type: boolean
          title: Broadcast
          description: Broadcast on-chain (requires EARN_SWEEP_AUTODISPATCH=true)
          default: false
        threshold_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Threshold Usd
          description: Override default $1.00 threshold
      type: object
      title: SweepBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
x-provenance:
  method: harvested
  publisher: Hive Civilization
  source: https://receipts.thehiveryiq.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)

Hive Civilization Earn API

Operations 8

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification