AGT Names API

openapi: 3.1.0
info:
  title: AGT Names API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 28 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; AGT Names has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 7
    documentation: 21
    pages-with-code: 7
    pages-read: 8
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://agtnames.com/docs/api-reference
  - https://agtnames.com/docs/examples
  - https://agtnames.com/docs/claude-code
  - https://agtnames.com/docs/quickstart
  - https://agtnames.com/docs/guides/discover-and-connect
  - https://agtnames.com/docs/guides/publish-identity
  - https://agtnames.com/docs/integrations
  - https://agtnames.com/docs/user-flows
paths:
  /:
    post:
      operationId: post
      tags:
      - Api
      summary: POST /
      x-source: https://agtnames.com/docs/examples
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST https://polygon-bor-rpc.publicnode.com -H \"content-type: application/json\" -d '{\n \"jsonrpc\":\"2.0\",\"\
          id\":1,\"method\":\"eth_call\",\n \"params\":[{\"to\":\"0x5B9386C47395B0551c814cC03b69cbD20eb0C87A\",\n \"data\":\"0x6352211ebf3aaa703a20e05fb493f618a2546ee4f3e5994bc8226825d6797c420ea611e0\"\
          },\"latest\"]}'"
  /.well-known/agt.json:
    get:
      operationId: get_well_known_agt_json
      tags:
      - API
      summary: 'The registry described for machines: chain, contract addresses, API routes, feeds, install commands, the spec URL.'
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /activity/feed.json:
    get:
      operationId: get_activity_feed_json
      tags:
      - Activity
      summary: The newest 100 activity rows as JSON Feed 1.1.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /activity/feed.xml:
    get:
      operationId: get_activity_feed_xml
      tags:
      - Activity
      summary: The newest 100 activity rows as Atom.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/agents:
    get:
      operationId: get_api_agents
      tags:
      - Api
      summary: 'The agent directory: every active name the indexer knows, with the endpoint records it has on chain and the capability ids from
        its verified manifest.'
      description: Returns JSON list of agents; includes domain, version, protocols, capabilities, endpoints, etc.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: protocol
        in: query
        required: false
        schema:
          type: string
        description: Filter by protocol (mcp, a2a, http, ws)
      - name: capability
        in: query
        required: false
        schema:
          type: string
        description: Exact capability id to filter
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Text match on name and description
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiAgentsResponse'
      x-evidence:
        kind: documentation
  /api/badge/<label>.svg:
    get:
      operationId: get_api_badge_label_svg
      tags:
      - Api
      summary: The on-chain identity badge for any valid label as SVG — the same art a mint embeds, so it renders for names that are not registered
        yet.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiBadgeLabelSvgResponse'
      x-evidence:
        kind: documentation
  /api/badge/demoagent.svg:
    get:
      operationId: get_api_badge_demoagent_svg
      tags:
      - Api
      summary: GET /api/badge/demoagent.svg
      x-source: https://agtnames.com/docs/quickstart
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiBadgeDemoagentSvgResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -o demoagent.svg "https://agtnames.com/api/badge/demoagent.svg" The HTTP API is convenient for lookups and directory queries;
          it reads the same chain the SDK does. Routes, responses and rate limits are in the API Reference . terminal sh Copy # 1. tokenId = namehash("demoagent.agt")
          — any keccak256 implementation works; the CLI does it offline:

          npx agt-resolve namehash demoagent.agt'
  /api/checkout:
    post:
      operationId: post_api_checkout
      tags:
      - Api
      summary: Card checkout for a new name (Stripe Checkout with server-side price verification).
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiCheckoutRequest'
      responses:
        '503':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiCheckoutResponse'
      x-evidence:
        kind: documentation
  /api/checkout/status:
    get:
      operationId: get_api_checkout_status
      tags:
      - Api
      summary: Poll fulfillment after a card payment.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: session_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCheckoutStatusResponse'
      x-evidence:
        kind: documentation
  /api/claim/status:
    get:
      operationId: get_api_claim_status
      tags:
      - Api
      summary: Legacy name Mint status for a name on the registry.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: domain
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiClaimStatusResponse'
      x-evidence:
        kind: documentation
  /api/health:
    get:
      operationId: get_api_health
      tags:
      - Api
      summary: Health check endpoint.
      description: Returns JSON indicating service health.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiHealthResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_health
      tags:
      - Api
      summary: POST /api/health
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiHealthRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiHealthResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl https://agtnames.com/api/health response json Copy { "ok": true, "service": "agt-site", "registryMode": "claims-only",
          "durableStorage": true, "time": "2026-09-13T00:22:47.994Z" } registryMode is claims-only while migration is open and new-name sales
          are closed; it becomes v2 at the sales cutover. Holders GET /api/v2/activity Live Rate limit: 60 per minute What happened on the registry:
          total'
  /api/notify:
    post:
      operationId: post_api_notify
      tags:
      - Api
      summary: POST /api/notify
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiNotifyRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiNotifyResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://agtnames.com/api/notify  -H "content-type: application/json"  -d ''{"email":"you@example.com","label":"exampleagent"}''
          response json Copy { "success": true, "created": true } // "created": false on a repeat Manifest POST /api/v2/manifest/pin Live Rate
          limit: 10 per minute Pin a signed v3 manifest whose signer is the name''s current on-chain owner. The server never signs; it only'
  /api/search:
    get:
      operationId: get_api_search
      tags:
      - Api
      summary: GET /api/search
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiSearchResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://agtnames.com/api/search?name=demoagent\" response — a registered name json Copy {\n \"success\": true, \"name\"\
          : \"demoagent\", \"fullDomain\": \"demoagent.agt\", \"registry\": \"v2\",\n \"tier\": \"standard\", \"registrationOpen\": true,\n \"\
          status\": \"unavailable\", \"available\": false, \"reserved\": false,\n \"price\": null, \"registerUsd\": 10, \"renewUsd\": 10, \"priceNote\"\
          : \"per year\"\n} response — an available name"
  /api/v2/activity:
    get:
      operationId: get_api_v2_activity
      tags:
      - Api
      summary: 'What happened on the registry: totals for every live name plus the last window by kind and recent events.'
      description: Returns JSON with summary totals and recent events.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: hours
        in: query
        required: false
        schema:
          type: string
        description: Window size in hours, default 24, max 720
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum events to return, default 50, max 200
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2ActivityResponse'
      x-evidence:
        kind: documentation
  /api/v2/agent-card/{label}:
    get:
      operationId: get_api_v2_agent_card_label
      tags:
      - Api
      summary: An A2A agent card for the name, built from its verified manifest.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: label
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2AgentCardLabelResponse'
      x-evidence:
        kind: documentation
  /api/v2/agent-card/notary:
    get:
      operationId: get_api_v2_agent_card_notary
      tags:
      - Api
      summary: GET /api/v2/agent-card/notary
      x-source: https://agtnames.com/docs/integrations
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl https://agtnames.com/api/v2/agent-card/notary
  /api/v2/allowlist:
    get:
      operationId: get_api_v2_allowlist
      tags:
      - Api
      summary: The migration allowlist.
      description: Returns JSON allowlist entries; 404 when not on list, 503 until published.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: address
        in: query
        required: true
        schema:
          type: string
        description: Wallet address
      - name: label
        in: query
        required: false
        schema:
          type: string
        description: Specific label to retrieve single proof
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2AllowlistResponse'
      x-evidence:
        kind: documentation
  /api/v2/manifest/pin:
    post:
      operationId: post_api_v2_manifest_pin
      tags:
      - Api
      summary: Pin a signed v3 manifest whose signer is the name's current on-chain owner.
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2ManifestPinRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2ManifestPinResponse'
      x-evidence:
        kind: documentation
  /api/v2/names:
    get:
      operationId: get_api_v2_names
      tags:
      - Api
      summary: Every Registry v2 name a wallet owns, from the index.
      description: Returns JSON list of names owned by the wallet; 400 for malformed address, 503 if index unavailable.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
        description: Wallet address to query
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2NamesResponse'
      x-evidence:
        kind: documentation
  /api/v2/quote:
    post:
      operationId: post_api_v2_quote
      tags:
      - Api
      summary: An EIP-712 registration or renewal quote for the on-chain checkout path.
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2QuoteRequest'
      responses:
        '404':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2QuoteResponse'
      x-evidence:
        kind: documentation
  /api/v2/zone-claim/challenge:
    post:
      operationId: post_api_v2_zone_claim_challenge
      tags:
      - Api
      summary: Start a zone-owner challenge and get the TXT record to add.
      description: Returns JSON with challenge details; rate limit 20 per minute.
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2ZoneClaimChallengeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2ZoneClaimChallengeResponse'
      x-evidence:
        kind: documentation
  /api/v2/zone-claim/mine:
    get:
      operationId: get_api_v2_zone_claim_mine
      tags:
      - Api
      summary: List zone-claim challenges owned by a wallet.
      description: Returns JSON list of claims.
      x-source: https://agtnames.com/docs/api-reference
      parameters:
      - name: wallet
        in: query
        required: true
        schema:
          type: string
        description: Wallet address
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV2ZoneClaimMineResponse'
      x-evidence:
        kind: documentation
  /api/v2/zone-claim/verify:
    post:
      operationId: post_api_v2_zone_claim_verify
      tags:
      - Api
      summary: Check the TXT record. On success the label and wallet are queued for the next allowlist publication.
      description: Returns 200 on success, 404 if zone missing, 409 if TXT mismatch, 503 if resolver unreachable.
      x-source: https://agtnames.com/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2ZoneClaimVerifyRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV2ZoneClaimVerifyResponse'
      x-evidence:
        kind: documentation
  /llms-full.txt:
    get:
      operationId: get_llms_full_txt
      tags:
      - Llms Full
      summary: A plain‑text map of the docs plus the manifest specification and the full capability vocabulary.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /llms.txt:
    get:
      operationId: get_llms_txt
      tags:
      - Llms
      summary: A plain‑text map of the docs.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /mcp:
    get:
      operationId: get_mcp
      tags:
      - Mcp
      summary: GET /mcp
      x-source: https://agtnames.com/docs/claude-code
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: 'http https://scraper.example/mcp" When an agent publishes a verified MCP endpoint, the natural next step is to register that
          endpoint as a second server and use the agent''s tools directly. The skill offers the claude mcp add command rather than running it:
          connecting to a third party is your decisio'
  /sitemap.xml:
    get:
      operationId: get_sitemap_xml
      tags:
      - Sitemap
      summary: Every docs, capability and name page; a name's lastmod is its newest activity row.
      x-source: https://agtnames.com/docs/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostRequest:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: integer
        method:
          type: string
        params:
          type: array
          items:
            type: object
            properties:
              to:
                type: string
              data:
                type: string
    GetApiAgentsResponse:
      type: object
      properties:
        success:
          type: boolean
        count:
          type: integer
        agents:
          type: array
          description: List of agent objects
    GetApiBadgeLabelSvgResponse:
      type: object
      properties:
        body:
          type: string
          description: SVG image data.
    GetApiBadgeDemoagentSvgResponse:
      type: object
      properties:
        name:
          type: string
        arguments:
          type: object
          properties:
            name:
              type: string
    PostApiCheckoutRequest:
      type: object
      properties:
        domain:
          type: string
        walletAddress:
          type: string
        email:
          type: string
        termsAccepted:
          type: boolean
        years:
          type: integer
      required:
      - domain
      - walletAddress
      - termsAccepted
      - years
    PostApiCheckoutResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        registrationOpen:
          type: boolean
    GetApiCheckoutStatusResponse:
      type: object
      properties:
        fulfillment_status:
          type: string
        domain:
          type: string
        walletAddress:
          type: string
        txHash:
          type: string
        mint_after:
          type: string
    GetApiClaimStatusResponse:
      type: object
      properties:
        success:
          type: boolean
        status:
          type: string
        transactionHash:
          type: string
        tokenId:
          type: string
        contract:
          type: string
        registry:
          type: string
        owner:
          type: string
    GetApiHealthResponse:
      type: object
      properties:
        ok:
          type: boolean
        service:
          type: string
        registryMode:
          type: string
        durableStorage:
          type: boolean
        time:
          type: string
    PostApiHealthRequest:
      type: object
      properties:
        label:
          type: string
        wallet:
          type: string
    PostApiHealthResponse:
      type: object
      properties:
        ok:
          type: boolean
        service:
          type: string
        registryMode:
          type: string
        durableStorage:
          type: boolean
        time:
          type: string
          format: date-time
    PostApiNotifyRequest:
      type: object
      properties:
        email:
          type: string
        label:
          type: string
    PostApiNotifyResponse:
      type: object
      properties:
        success:
          type: boolean
        created:
          type: boolean
    GetApiSearchResponse:
      type: object
      properties:
        success:
          type: boolean
        name:
          type: string
        fullDomain:
          type: string
        registry:
          type: string
        tier:
          type: string
        registrationOpen:
          type: boolean
        status:
          type: string
        available:
          type: boolean
        reserved:
          type: boolean
        price:
          type:
          - string
          - 'null'
        registerUsd:
          type: integer
        renewUsd:
          type: integer
        priceNote:
          type: string
    GetApiV2ActivityResponse:
      type: object
      properties:
        summary:
          type: object
        events:
          type: array
    GetApiV2AgentCardLabelResponse:
      type: object
      properties:
        protocolVersion:
          type: string
          description: Version of the card protocol.
        name:
          type: string
          description: Full domain name (e.g., notary.agt).
        description:
          type: string
          description: Human‑readable description of the agent.
        url:
          type: string
          description: A2A endpoint URL.
        preferredTransport:
          type: string
          description: Transport protocol (e.g., JSONRPC).
        version:
          type: string
          description: Version timestamp of the card.
        provider:
          type: object
          description: Information about the provider organization.
        capabilities:
          type: object
          description: Supported capability flags.
        defaultInputModes:
          type: array
          description: Default input MIME types.
        defaultOutputModes:
          type: array
          description: Default output MIME types.
        skills:
          type: array
          description: List of skill objects with id, name, description, tags.
        documentationUrl:
          type: string
          description: URL to the name’s documentation page.
        supportsAuthenticatedExtendedCard:
          type: boolean
          description: Whether the card supports authenticated extensions.
    GetApiV2AllowlistResponse:
      type: object
      properties:
        root:
          type: string
        claimant:
          type: string
        entries:
          type: array
          description: List of {label, proof}
    PostApiV2ManifestPinRequest:
      type: object
      properties:
        manifest:
          type: object
          description: Signed manifest v3 object containing agt, name, owner, signature, etc.
      required:
      - manifest
    PostApiV2ManifestPinResponse:
      type: object
      properties:
        uri:
          type: string
          description: IPFS URI of the pinned manifest.
        cid:
          type: string
          description: Content identifier.
        provider:
          type: string
          description: Pinning provider (e.g., pinata).
        label:
          type: string
          description: Label of the name.
        owner:
          type: string
          description: Owner address.
    GetApiV2NamesResponse:
      type: object
      properties:
        owner:
          type: string
        count:
          type: integer
        names:
          type: array
          description: List of name objects
    PostApiV2QuoteRequest:
      type: object
      properties:
        label:
          type: string
        to:
          type: string
        years:
          type: integer
          description: Defaults to 1.
        payToken:
          type: string
          description: '"usdc" | "native"'
        renew:
          type: boolean
      required:
      - label
      - to
      - payToken
    PostApiV2QuoteResponse:
      type: object
      properties:
        error:
          type: string
    PostApiV2ZoneClaimChallengeRequest:
      type: object
      properties:
        label:
          type: string
        wallet:
          type: string
      required:
      - label
      - wallet
    PostApiV2ZoneClaimChallengeResponse:
      type: object
      properties:
        label:
          type: string
        wallet:
          type: string
        code:
          type: string
        record:
          type: object
        validForDays:
          type: integer
        instructions:
          type: array
    GetApiV2ZoneClaimMineResponse:
      type: object
      properties:
        wallet:
          type: string
        claims:
          type: array
          description: Each claim includes label, method, verifiedAt, published
    PostApiV2ZoneClaimVerifyRequest:
      type: object
      properties:
        label:
          type: string
        wallet:
          type: string
      required:
      - label
      - wallet
    PostApiV2ZoneClaimVerifyResponse:
      type: object
      properties:
        verified:
          type: boolean
        method:
          type: string
        next:
          type: string
        error:
          type: string
        txtSeen:
          type: array
tags:
- name: API
- name: Activity
- name: Api
- name: Llms
- name: Llms Full
- name: Mcp
- name: Sitemap