Migrating an Existing OpenAI SDK App to the Aggregator's /chat/completions Endpoint

Why Migrate to the Aggregator's /chat/completions Endpoint

If you already use the OpenAI SDK, moving to the aggregator is straightforward. The aggregator provides an OpenAI-compatible /chat/completions endpoint, so your existing code can work with just two configuration changes: the base URL and the API key. This lets you access multiple models (such as Claude, GPT, DeepSeek, Qwen, GLM, and Kimi) through one API key, with billing in USDC on Base and no KYC.

Prerequisites

Before you begin, ensure you have:

• An existing application using the OpenAI SDK (Python, Node.js, or similar).
• An aggregator account with a funded balance. You can top up with USDC on Base.
• Your aggregator API key (available from your dashboard).

Step 1: Update the Base URL

The OpenAI SDK allows you to override the default API endpoint by setting the base_url parameter (Python) or baseURL (Node.js). Replace the default with the aggregator's base URL.

Python example:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aggregator.example/v1",  # Replace with actual base URL
    api_key=os.environ["AGGREGATOR_API_KEY"]
)

Node.js example:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.aggregator.example/v1',
  apiKey: process.env.AGGREGATOR_API_KEY
});

Note: The aggregator's documentation will provide the exact base URL. Ensure it ends with /v1 if required.

Step 2: Switch the API Key Environment Variable

Instead of using OPENAIAPIKEY, use a new environment variable for your aggregator key. This keeps your OpenAI credentials separate and makes it easy to switch back if needed.

1. Generate an API key in your aggregator dashboard.
2. Add it to your environment:

```bash
export AGGREGATORAPIKEY="your-aggregator-key"
```

3. Update your code to read from AGGREGATORAPIKEY instead of OPENAIAPIKEY.

In Python:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.aggregator.example/v1",
    api_key=os.environ["AGGREGATOR_API_KEY"]
)

In Node.js:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.aggregator.example/v1',
  apiKey: process.env.AGGREGATOR_API_KEY
});

Step 3: Verify the Response Shape

The aggregator's /chat/completions endpoint returns responses in the same format as OpenAI's API. This means your existing parsing logic should work without modification. However, it's good practice to verify.

Send a test request:

response = client.chat.completions.create(
    model="gpt-4",  # or any supported model
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

The response object will have the same structure: id, object, created, model, choices, usage, etc. The choices array contains message objects with role and content. If your code accesses response.choices[0].message.content, it will continue to work.

If you use streaming, the chunk format is also identical. Test with:

stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Step 4: Adjust Model Names (If Needed)

The aggregator supports multiple models from different providers. Model names may differ from OpenAI's naming convention. For example, instead of gpt-4, you might use gpt-4 (if supported) or a provider-specific name like claude-3-opus or deepseek-chat. Check the aggregator's documentation for the exact model identifiers.

If you want to keep your code flexible, consider making the model name configurable via an environment variable or configuration file.

Step 5: Handle Errors and Rate Limits

The aggregator may return errors in the same format as OpenAI, but with different error codes or messages. Ensure your error handling is robust and checks for HTTP status codes. Common errors include:

• 401 Unauthorized: Invalid API key.
• 402 Payment Required: Insufficient balance (top up with USDC on Base).
• 429 Too Many Requests: Rate limit exceeded.

Implement retries with exponential backoff for transient errors.

Step 6: Test Thoroughly

Run your application's test suite against the aggregator. Pay attention to:

• Authentication: Ensure the API key is correctly loaded.
• Model responses: Verify that outputs are as expected.
• Streaming: Check that streaming works and chunks are parsed correctly.
• Error handling: Simulate errors (e.g., invalid key) to ensure graceful degradation.

Billing and Cost Considerations

When you use the aggregator, you pay the official model price multiplied by 1.3. If you contribute keys, you are credited official price × 1.1 (or × 1.2 for premium) in USDC. This means your effective cost is higher than going directly to the provider, but you gain the convenience of a single API key, multiple models, and no KYC. Top up with USDC on Base to maintain a positive balance.

Conclusion

Migrating your OpenAI SDK app to the aggregator's /chat/completions endpoint requires only changing the base URL and API key environment variable. The response shape remains identical, so your existing code should work with minimal adjustments. You can then access a variety of models through one key, with transparent USDC billing on Base. Always refer to the aggregator's official documentation for the most up-to-date details.