# Integrate SDK
The openseed-sdk is the programmatic interface to the OpenSeed protocol for developers who need to integrate OpenSeed functionality directly into their applications rather than operating standalone nodes through the CLI or Dashboard. It is a JavaScript and TypeScript library that exposes the complete OpenSeed protocol stack as composable, well-documented modules with a clean, idiomatic API.
### Overview and Use Cases
The SDK is intended for three primary use cases. The first is building custom Buyer implementations — applications that need to consume AI inference through the OpenSeed network in ways that require more control than the standard Buyer proxy provides. This might include applications that need to implement custom routing logic, manage multiple concurrent payment channels programmatically, or integrate OpenSeed payments into a larger financial system.
The second use case is building custom Seller implementations — applications that want to offer AI inference through the OpenSeed network in ways that require more customization than the standard Seller node configuration supports. This might include applications that wrap proprietary models, implement custom pricing logic based on request characteristics, or integrate OpenSeed payment collection into an existing API service.
The third use case is building ecosystem tooling — applications that interact with the OpenSeed network for purposes other than direct inference consumption or provision. This includes analytics platforms, network monitoring tools, Registry explorers, reputation scoring services, and governance tooling.
The SDK is published to the npm registry under the openseed-sdk package name. It is fully typed with TypeScript definitions and ships with comprehensive JSDoc documentation for all public APIs.
### Module Architecture
The SDK is organized into six core modules, each encapsulating a specific layer of the OpenSeed protocol.
The Network module provides the interface to the Registry and peer discovery system. It handles Registry queries, peer list fetching and filtering, heartbeat management for Seller nodes, and Registry subscription for real-time peer list updates. This is the module you use when you need to discover providers programmatically or implement custom discovery logic.
The Wallet module manages all cryptographic operations related to EVM signing. It handles private key management, EIP-712 signature generation, transaction construction for ReserveAuth operations, and nonce management. This module abstracts the low-level cryptographic operations so that higher-level modules do not need to interact with raw signing primitives.
The Channel module manages the state of payment channels — tracking open channels, their balances, accumulated SpendingAuths, and expiration times. It provides the logic for determining when a new ReserveAuth is needed, when a channel should be topped up, and when accumulated SpendingAuths should be submitted for settlement.
The Seller module provides the x402 middleware that wraps an upstream inference endpoint with payment collection logic. It handles incoming requests, invoice generation, SpendingAuth validation, and the accumulation of validated authorizations for settlement. This is the module that Seller node implementations are built on.
The Buyer module implements the Buyer proxy logic — request routing, provider selection, payment handshake execution, fallback handling, and response forwarding. Custom Buyer implementations can use this module's components selectively, replacing only the parts that need customization while leveraging the rest.
The Analytics module provides access to historical usage and performance data stored by Buyer and Seller nodes. It is the programmatic equivalent of the Dashboard's analytics features, providing queryable access to request logs, spending history, and reputation metrics.
\[Full SDK API reference with type signatures, parameter descriptions, return types, error handling, and usage examples will be documented here for each module and its public methods]
### TypeScript Support and Type Safety
The openseed-sdk is written in TypeScript and ships with complete type definitions for all public APIs. The type system covers all protocol data structures — invoice formats, SpendingAuth structures, Registry peer records, channel state objects, and analytics data — as well as all configuration objects and method signatures.
This means that TypeScript users get full IDE autocomplete and static type checking for all SDK interactions. The types are designed to be strict where strictness matters — payment amounts are typed as BigInt to prevent floating-point errors, addresses are typed as validated hex strings, and all optional fields are explicitly typed as nullable.
\[TypeScript usage examples and type reference will be documented here]
### Error Handling and Edge Cases
The SDK implements a comprehensive error taxonomy that covers all expected failure modes in OpenSeed network interactions. Errors are typed and carry structured metadata — for example, a PaymentChannelError includes the channelId and the specific reason for failure, a ProviderError includes the Seller node ID and the HTTP status code returned, and a SignatureError includes the verification failure reason.
\[Full error taxonomy and handling patterns will be documented here]
---
# 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/integrate-sdk.md?ask=
```
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.