Can I use the API without the SDK?

Yes. The API is a standard REST interface. Any language capable of making HTTP requests and handling bearer token authentication can integrate directly, without using our SDK.

How long is a settled session token valid?

Session tokens are valid for the current operational session. If an agent closes and reopens, or if the session expires, a new $0.01 settlement is required to access a vault node again.

Integrating Sovereign Knowledge: A Technical Blueprint |…

Step 1: Discovery via the Manifest

Every integration begins with the discovery manifest. Your agent should query https://bidda.com/api/v1/nodes/index.json or parse https://bidda.com/llms-full.txt to retrieve the list of available Node IDs and their associated metadata. This allows the agent to identify the relevant node for its current task without relying on vector search or LLM-generated guesses.

Step 2: Querying the Free Metadata Endpoint

Before settling payment, the agent can retrieve the free node metadata via GET /api/v1/nodes/[NODE_ID]. This returns the BLUF summary, authority citation, jurisdiction scope, and the SHA-256 integrity hash. For many compliance-checking tasks, the BLUF alone is sufficient to inform a decision without requiring vault access.

Step 3: Handling the 402 Payment Challenge

When full intelligence is required, the agent calls GET /api/v1/vault/[NODE_ID]. If the session has no valid bearer token, the server returns an HTTP 402 Payment Required response containing an L402 invoice. Your agent's Web3 payment stack settles this invoice and attaches the signed receipt as a bearer token in the Authorization header of the retry request.

Step 4: Implementing the Verified Loop

After ingesting the intelligence payload, your agent should verify the returned SHA-256 hash against the value in the public registry index. This Verified Loop provides a real-time tamper check, ensuring that the intelligence being used for decision-making precisely matches the official signed standard at that moment.

Step 5: Caching and Receipt Storage

Settled L402 tokens are valid for the duration of the current session. Agents should cache the receipt securely in memory and reuse it for subsequent calls to the same node within the session window. If the session expires and the agent requires the same node again, a new settlement is required. This ensures that intelligence consumption remains measurable and auditable per operational session.

SDK and Language Support

Our Phase 1 SDK is optimised for TypeScript and Node.js environments with native support for L402 invoice parsing, wallet provider abstraction, and hash verification utilities. However, the underlying API is a standard REST interface - any language or framework capable of making HTTPS requests and handling JWT-style bearer tokens can integrate with the Sovereign Forest.

Integrating Sovereign Knowledge: A Technical Blueprint