# API Reference

The OpenSeed network exposes three distinct HTTP API surfaces. The Registry API is the public interface to the peer discovery network. The Seller Node API is the interface presented by each Seller node — both to Buyers executing the x402 payment handshake and to operators managing the node. The Buyer Proxy API is the interface the Buyer proxy presents to local applications.

Understanding these three APIs is important for developers building integrations, tools, or custom implementations that interact with the OpenSeed network at the protocol level rather than through the higher-level SDK abstractions.

### API Design Conventions

All OpenSeed APIs follow consistent conventions. Request and response bodies use JSON encoding with UTF-8 encoding. Authentication is handled through EIP-712 signatures embedded in request headers rather than through API keys or OAuth tokens. Error responses follow a consistent structure with a numeric error code, a machine-readable error type string, and a human-readable message.

Pagination is implemented consistently across all list endpoints using cursor-based pagination rather than offset-based pagination, which is more reliable for frequently-updating datasets like the Registry peer list.

All timestamp fields use Unix timestamp integers (seconds since epoch). All USDC amounts use BigInt-compatible string representations of the amount in micro-USDC (millionths of a USDC) to avoid floating-point precision issues.

Rate limiting is applied at the IP level for public endpoints and at the wallet address level for authenticated endpoints. Rate limit headers follow the standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset convention.

### The Registry API

The Registry API is the public entry point to the OpenSeed peer discovery network. It is hosted at the canonical Registry endpoint and is accessible to any client without authentication for read operations. Write operations (registration and heartbeats) require valid EIP-712 signatures from the registering Seller's wallet.

The Registry API provides endpoints for querying the active peer list with filtering by model, price cap, and minimum reputation score; retrieving detailed information about a specific node by node ID; registering a new Seller node; sending heartbeats to maintain active status; and querying aggregate market statistics including current price ranges and traffic volumes by model.

\[Full Registry API endpoint documentation with HTTP methods, URL patterns, request schemas, response schemas, example requests and responses, error codes, and rate limit specifications will be documented here]

### The Seller Node API

Every Seller node exposes an HTTP API at its public endpoint. This API serves two distinct audiences: Buyers executing inference requests through the x402 payment protocol, and the Seller operator managing the node.

For Buyers, the API is OpenAI-compatible at the inference layer. It exposes the standard /v1/chat/completions, /v1/completions, and /v1/models endpoints that any OpenAI-compatible client can speak. The x402 payment logic is layered transparently on top — Buyers simply receive a 402 response when no authorization is present, and the OpenAI-compatible interface is restored once a valid SpendingAuth is provided.

For operators, the API exposes management endpoints for checking node status, viewing accumulated earnings, inspecting the channel state with individual Buyers, and triggering settlement transactions. These management endpoints require authentication via a locally-generated signature that confirms operator identity.

\[Full Seller Node API documentation covering both the OpenAI-compatible inference endpoints and the management endpoint suite, with complete schema definitions and authentication requirements, will be documented here]

### The Buyer Proxy API

The Buyer proxy exposes two API surfaces on the local machine. The OpenAI-compatible inference API is the primary surface — it is the interface that AI tools and applications interact with, and it is by design indistinguishable from the standard OpenAI API. This surface requires no documentation beyond OpenAI's existing API documentation, since it is fully compatible.

The management API is the secondary surface — a local-only HTTP interface that provides programmatic access to the proxy's internal state and controls. It exposes endpoints for querying current channel state and balances, reading request history and analytics, modifying routing preferences, triggering manual operations like channel top-up, and configuring provider preferences and filters.

\[Full Buyer Proxy management API documentation with all endpoints, authentication requirements, schema definitions, and integration examples will be documented here]

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openseed.gg/integrations/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.