OpenAI API compatibility is a distribution strategy, not an integration

A lot of decentralized AI projects describe themselves as “OpenAI-compatible” and then ship a schema that is almost OpenAI but not quite. The roles array uses different names. The streaming format swaps data: for something custom. The error responses follow their own shape. The integration tax is two days of debugging instead of zero.

SolanaLM speaks OpenAI’s schema exactly. Not “OpenAI-style.” Not “OpenAI-compatible-ish.” The actual schema, including all the warts. This post is about why that boring decision is load-bearing for distribution.

The cost of any incompatibility is amortized over every integration

Consider an application that currently uses OpenAI. To switch to SolanaLM, the developer has to:

1. Change the base URL.
2. Change the API key.

That is the entire integration if we are truly compatible. Their existing test suite, their request retry logic, their streaming consumer, their error handling — all of it keeps working.

Now consider a partial compatibility story: “we are OpenAI-compatible except we use wallet instead of api_key and our streaming sends NDJSON instead of SSE.” The integration becomes:

1. Change the base URL.
2. Change the API key.
3. Refactor the auth header construction.
4. Rewrite the streaming consumer.
5. Update error parsing because shapes differ.
6. Add a feature flag to gate the migration.
7. Discover three more edge cases in QA.
8. Find one more after rollout.

Each one of those steps is small. The sum is “we will get to it next quarter.” That is the silent killer for any decentralized provider: not a hard “no,” but a permanent “not yet.”

The full OpenAI compatibility decision is therefore not about technical elegance. It is about removing the procrastination surface. When the switch is two lines, it happens this afternoon. When it is twenty lines, it happens never.

What we actually copy

The endpoints:

• POST /v1/chat/completions
• POST /v1/completions
• POST /v1/embeddings
• GET /v1/models

The request shapes match OpenAI exactly. We support messages, temperature, top_p, max_tokens, stream, tools, tool_choice, response_format. Where OpenAI added a parameter we do not implement (e.g., logprobs), we accept it silently rather than rejecting the request. The rule we follow is: accept anything OpenAI accepts; reject only what they would reject.

The response shapes match exactly. The choices array, the usage object, the finish_reason enum values, the id prefix conventions — we mirror all of them.

Streaming follows SSE with data: {json} lines and a terminal data: [DONE]. Each chunk is a chat.completion.chunk object with deltas. The OpenAI Python SDK’s iterator works against our endpoint unchanged.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.solanalm.io/v1",
    api_key="SolanaWalletAddressBase58Encoded",
)

stream = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "Hello."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

That code is unchanged from a vanilla OpenAI integration. Only the constructor differs.

What we extend (carefully)

We do add SolanaLM-specific features, but we add them as additive fields that OpenAI clients ignore safely.

Privacy circuit length. A request can include x_solanalm_privacy_hops: 3 in the metadata. We route through a 3-hop onion circuit. Clients that do not set it get default direct routing.

Wallet routing hints. Clients can prefer specific operator wallets or reputation tiers via x_solanalm_routing metadata.

Per-token settlement. Clients can opt into per-token rather than per-request settlement with x_solanalm_settlement_mode: "streaming".

These all live in fields that pass through OpenAI’s schema validation as unknown extras. They never break the standard contract.

Where compatibility costs us

A few places.

Tool calling semantics. OpenAI’s tool calling assumes a single trusted endpoint enforcing tool-use policy. In a multi-node decentralized network, we have to reconcile “which node executes the tool” with the original OpenAI assumption. We currently dispatch tool calls back to the client; OpenAI’s hosted tools do not work directly.

Function calling deprecation. OpenAI deprecated functions in favor of tools. We support both, mostly because client code in the wild still uses the older shape.

Vision and audio. OpenAI’s multimodal endpoints assume hosted file storage. We have to use external storage references because we do not host customer files. The schema works the same; the operational story is different.

Rate limiting. OpenAI’s 429 responses include specific headers (x-ratelimit-remaining-requests). We emit those headers but the underlying logic is per-wallet rather than per-API-key.

We could fork the schema to fix these. We choose not to. The cost of a clean schema we control is two days of every integration. The cost of OpenAI compatibility is some internal awkwardness in our gateway.

What this looks like operationally

Compatibility is not free to maintain. The OpenAI API evolves. We track it. Our compatibility test suite hits both the OpenAI SDK and a vendored copy of OpenAI’s published schema fixtures. When OpenAI ships a new parameter, our CI sees it within a day. When they change a response shape, we update.

We treat it like a contract test against an external dependency. Because it is.

The alternative — “we did OpenAI-compatible in 2024 and never updated it” — is the path to actually-not-compatible. Every team that says “OpenAI compatible” without that test infrastructure is, on a long enough timeline, wrong about it.

Beyond OpenAI

Anthropic’s Messages API and Cohere’s Chat API have their own schemas. We do not implement them as gateway endpoints today. Our backend abstraction proxies them, so if you set up a SolanaLM node with an Anthropic backend, requests routed to it work — but the gateway speaks OpenAI’s schema regardless of which backend serves the request.

This is the right asymmetry. The OpenAI schema has the most clients targeting it. We optimize for the common case at the API surface and proxy to provider-specific shapes at the node.

The honest summary

Compatibility is not glamorous. It does not differentiate at the architecture-diagram level. It is also, empirically, the single biggest factor in whether a developer integrates your network this week or never.

We picked it. We will keep paying the maintenance cost. And every time someone tells us they integrated SolanaLM in twenty minutes, we feel that decision was right.