Provider Integration

A guide for data providers who want to add AIPC contracts to their existing APIs. Wrap your responses, define your rules, and let AI agents comply automatically.

Step 1: Wrap your response

Take your existing API response and nest it inside the AIPC envelope. Your original response becomes the payload:

// Before (your existing API)
{
  "ticker": "VFIAX",
  "price": 423.17,
  "currency": "USD"
}

// After (AIPC-wrapped)
{
  "aipc_version": "0.1.0",
  "provider": {
    "id": "your-company",
    "name": "Your Company, Inc.",
    "contract_version": "1.0.0"
  },
  "contract": { ... },
  "payload": {
    "ticker": "VFIAX",
    "price": 423.17,
    "currency": "USD"
  }
}

Step 2: Design your contract

Start with the essentials and add complexity as needed:

  1. Attribution — Who provided this data? What text must appear?
  2. Disclosures — What legal or regulatory text must accompany the data?
  3. Display rules — How should numbers, dates, and values be formatted?
  4. Freshness — How long is this data valid? What happens when it expires?
  5. Fail behavior — What if the AI can't comply? Start with "suppress".

Add tone restrictions and conditional rules once the basics are working.

Step 3: Version your contracts

Use the provider.contract_version field to track contract changes. When you add a new disclosure or change a display rule, bump the version. AI runtimes can use this for cache invalidation and audit trails.

"provider": {
  "id": "morningstar",
  "name": "Morningstar, Inc.",
  "contract_version": "2.1.0"
}

Step 4: Test with the runtime

Validate your contracts before deploying them. The runtime catches common mistakes:

import { AIPCRuntime } from '@aipc/runtime';

const runtime = new AIPCRuntime();
const result = runtime.validate(yourResponse);

// Check for issues
if (result.warnings.length > 0) {
  console.warn('Contract warnings:', result.warnings);
}
if (!result.success) {
  console.error('Contract errors:', result.errors);
}

Step 5: Support opt-in

Not all consumers need AIPC. Consider supporting both wrapped and unwrapped responses:

// Consumer requests AIPC format via header
GET /api/fund/VFIAX
Accept: application/aipc+json

// Or via query parameter
GET /api/fund/VFIAX?format=aipc

When the consumer requests standard JSON, return your existing response. When they request AIPC, wrap it with the contract envelope.

Common patterns

  • Shared contracts — Many endpoints may share the same disclosures and tone restrictions. Define your contract once and reference it across endpoints.
  • Per-endpoint display rules — While disclosures are often shared, display rules tend to be specific to each endpoint's payload structure.
  • Dynamic freshness — Set valid_until relative to your data update frequency. Stock prices may expire in minutes; fund metadata may be valid for days.