Skip to main content

Onboarding Integrations Runbook

This guide covers the process of adding new external API integrations (brokerages, data providers, etc.) and managing existing ones.

Overview​

AlphaSwarm uses a unified IntegrationSpec contract to define external connections. This allows for a consistent experience across the CLI, UI, and backend services.

Adding a New Integration​

1. Define the IntegrationSpec​

Create a new spec in alphaswarm_core or your specialized package:

from alphaswarm_core.integrations import IntegrationSpec, IntegrationCategory, ConnectMethod

MY_INTEGRATION = IntegrationSpec(
    slug="my-provider",
    display_name="My Data Provider",
    category=IntegrationCategory.MARKET_DATA,
    connect_method=ConnectMethod.API_KEY,
    # ... other fields
)

2. Register the Spec​

Register your spec in the global IntegrationRegistry:

from alphaswarm_core.integrations import get_integration_registry

registry = get_integration_registry()
registry.register(MY_INTEGRATION)

3. Implement the Adapter​

Implement the concrete adapter that communicates with the provider API. Refer to alphaswarm/integrations/brokerages.py for examples.

4. Update the UI​

The alphaswarm_client automatically renders integration forms based on the IntegrationSpec. Verify the new integration appears in the "Integrations" tab.

Managing Integrations via CLI​

Use the alphaswarm-cli brokers command group:

  • List available providers: alphaswarm brokers providers
  • Add a new connection: alphaswarm brokers add <provider-slug>
  • Test connection: alphaswarm brokers test <broker-id>

Common Configuration Fields​

FieldDescription
API_KEYPrimary authentication key.
API_SECRETSecret key (if required).
ENVIRONMENTsandbox, paper, or live.

Troubleshooting Integrations​

  • Authentication Failed: Verify that the credentials are correct and not expired. Check the CredentialResolver logs.
  • Rate Limited: Adjust the rate limit settings in the IntegrationSpec or the provider-specific configuration.
  • Provider Unreachable: Check the outbound proxy settings or the provider's status page.

Further Documentation​