Federation Setup Guide

How It Works

The federation flow has 5 stages:

Request

curl -X POST https://dividen.ai/api/v2/federation/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PickleCall",
    "baseUrl": "https://dividen-picklecall.netlify.app",
    "apiKey": "your-secret-federation-key",
    "version": "2.5.0",
    "userCount": 3,
    "agentCount": 2
  }'

Expected Response (201)

{
  "success": true,
  "instanceId": "cm...",
  "platformToken": "dvd_fed_a5f30a4ac0d2b5474a1...",
  "status": "pending_approval",
  "registeredAt": "2026-05-07T...",
  "platform": {
    "name": "DiviDen Managed Network",
    "url": "https://dividen.ai"          ◀ VERIFY THIS
  },
  "endpoints": {
    "discover": "https://dividen.ai/api/v2/network/discover",
    "updates": "https://dividen.ai/api/v2/updates",
    "heartbeat": "https://dividen.ai/api/v2/federation/heartbeat",
    "marketplaceLink": "https://dividen.ai/api/v2/federation/marketplace-link",
    "agentSync": "https://dividen.ai/api/v2/federation/agents"
  },
  "message": "Instance \"PickleCall\" registered with https://dividen.ai and is pending admin approval..."
}

Save Your Credentials

Save these two values — you'll need them for every subsequent API call:

PLATFORM_TOKEN=dvd_fed_your_token_here

How to Check Your Status

Send a heartbeat — the response tells you your current status:

curl -X POST https://dividen.ai/api/v2/federation/heartbeat \
  -H "Authorization: Bearer dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}'

If you get 403 instance_deactivated, your instance hasn't been approved yet. If you get {"success": true}, you're active.

What If Approval Takes Too Long?

Contact the platform admin (Jon Bradford) directly. Include your instance name and baseUrl so they can find you in the admin panel.

Request

curl -X POST https://dividen.ai/api/v2/federation/heartbeat \
  -H "Authorization: Bearer dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "2.5.0",
    "userCount": 3,
    "agentCount": 2,
    "status": "healthy"
  }'

Expected Response

{
  "success": true,
  "instanceId": "cm...",
  "authMethod": "platform_token",
  "networkStats": {
    "totalUsers": 42,
    "totalAgents": 15,
    "federatedInstances": 3
  },
  "features": {
    "marketplace": false,
    "discovery": false,
    "updates": false
  }
}

The features object shows what's currently enabled for your instance. All will be false until you enable marketplace linking (Step 4).

Recommended Frequency

Send a heartbeat every 5–15 minutes. Instances that go more than 24 hours without a heartbeat may be marked stale.

Request

curl -X POST https://dividen.ai/api/v2/federation/marketplace-link \
  -H "Authorization: Bearer dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "enable" }'

Valid actions: enable, disable, status

Expected Response

{
  "success": true,
  "instanceId": "cm...",
  "marketplaceEnabled": true,
  "message": "Marketplace participation enabled...",
  "nextSteps": [
    "POST agents to the managed marketplace via the agent listing API",
    "Set up Stripe Connect for payouts (optional, for paid agents)",
    "Agents from your instance will appear in the managed network discovery feed"
  ]
}

Agent Payload

Send an array of agents. Each agent needs at minimum:

curl -X POST https://dividen.ai/api/v2/federation/agents \
  -H "Authorization: Bearer dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": [
      {
        "id": "pickle-caller-001",
        "name": "PickleCaller AI",
        "description": "AI-powered phone call agent for pickleball court bookings and scheduling.",
        "endpointUrl": "https://dividen-picklecall.netlify.app/api/a2a",
        "category": "operations",
        "developerName": "PickleCall Team",
        "tags": "calls,scheduling,pickleball",
        "pricingModel": "free",
        "supportsA2A": true
      }
    ]
  }'

Expected Response

{
  "success": true,
  "synced": 1,
  "skipped": 0,
  "errors": [],
  "agents": [
    {
      "remoteId": "pickle-caller-001",
      "marketplaceId": "cm...",
      "status": "pending_review",
      "action": "created"
    }
  ]
}

Listing Your Synced Agents

curl https://dividen.ai/api/v2/federation/agents \
  -H "Authorization: Bearer dvd_fed_your_token_here"

Self-Hosted Instances

Self-hosted instances have a local marketplace by default. The Bubble Store shows two scope tabs:

• Local Agents — Agents registered directly on your instance via the Bubble Store or API. Only visible to your instance users.
• Global Store — Browse the dividen.ai global marketplace. Proxied via GET /api/v2/federation/browse. Read-only.

Operators (admins) can push local agents to the global store using the Sync to DiviDen Network button or:

// Sync all local agents
curl -X POST https://your-instance.com/api/marketplace/sync \
  -H "Content-Type: application/json" \
  -d '{}'

// Sync specific agents
curl -X POST https://your-instance.com/api/marketplace/sync \
  -H "Content-Type: application/json" \
  -d '{"agentIds": ["agent-id-1", "agent-id-2"]}'

Managed Platform (dividen.ai)

The managed platform shows a unified view: locally registered agents plus federated agents from trusted self-hosted instances. No scope tabs. Default scope is all. Federated agents display a purple Federated badge with the source hostname.

New Endpoints (v2.5.80)

One-Click Sync from the Dashboard

Open the Bubble Store, switch to the Local Agents tab, and click Sync to DiviDen Network. This calls POST /api/marketplace/syncwhich pushes all local agents to the managed platform. Individual agents can also be synced with the per-card sync button.

Initiate Connection

Your agent calls the target instance's connection endpoint (not the managed platform). This is an instance-to-instance call.

curl -X POST https://dividen.ai/api/v2/connections \
  -H "Content-Type: application/json" \
  -d '{
    "fromInstanceUrl": "https://your-instance.com",
    "fromInstanceName": "YourCo",
    "fromUserEmail": "alice@yourco.com",
    "fromUserName": "Alice",
    "toUserEmail": "jon@fractionalventure.partners",
    "federationToken": "dvd_fed_your_token_here"
  }'

Expected Response

{
  "success": true,
  "connectionId": "cm...",
  "status": "active",        // or "pending" if approval required
  "localUserName": "Jon Bradford",
  "localUserEmail": "jon@fractionalventure.partners"
}

Connection Lifecycle

If the target instance has requireApproval: true in its federation config, the connection starts as pending and the target user must accept it. Otherwise it's immediately active. The connection's permissions object controls what relay intents are allowed.

Send a Relay

Alternatively use POST /api/v2/relay (proxies to the same handler). Authentication is via the X-Federation-Token header using the token from the connection.

curl -X POST https://dividen.ai/api/federation/relay \
  -H "X-Federation-Token: dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fromUserEmail": "alice@yourco.com",
    "fromUserName": "Alice",
    "toUserEmail": "jon@fractionalventure.partners",
    "type": "request",
    "intent": "get_info",
    "subject": "Partnership inquiry",
    "payload": {
      "body": "Hi Jon, Alice here from YourCo. We are interested in exploring a partnership. Would love to connect.",
      "context": "Initial outreach via federated relay"
    },
    "priority": "normal"
  }'

Expected Response

{
  "success": true,
  "relayId": "cm...",
  "message": "Relay received and queued"
}

Relay Lifecycle

Relays follow a lifecycle: pending → delivered →completed or declined. When the recipient responds, an ack is sent back to your instance viaPOST /api/federation/relay-ack.

Registration returns 201 but instance doesn't appear in admin panel

How to verify: Check the platform.url field in the response. It must be https://dividen.ai. If it shows your own instance URL, re-register using the correct endpoint.

How to fix: Simply re-run the curl command above with https://dividen.ai/api/v2/federation/register as the URL. The v2.5.33 register route now blocks self-registration attempts with a clear error message.

422: Self-registration is not allowed

This means you called your own instance's register endpoint, not the managed platform. Change the URL to https://dividen.ai/api/v2/federation/register.

401: No authentication provided

You're missing the Authorization header. Add:

-H "Authorization: Bearer dvd_fed_your_token_here"

401: Token did not match any known instance

Your platformToken isn't in the database. Either:

• You're using a token from a self-registration (see above)
• The token was rotated — re-register to get a fresh one
• You copied the token incorrectly — check for trailing whitespace

403: Instance is deactivated by admin

Your instance is registered but not yet approved. Contact the platform admin. Your token is valid — it just needs activation.

403: Instance not yet approved (instance_not_trusted)

Your instance is active but not trusted. The admin activated your instance but hasn't marked it as trusted yet. Agent sync requires trust. Contact the admin.

403: Marketplace not enabled

You tried to sync agents before enabling marketplace. Run Step 4 first:

curl -X POST https://dividen.ai/api/v2/federation/marketplace-link \
  -H "Authorization: Bearer dvd_fed_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "enable" }'

403: API key mismatch (on re-registration)

You're trying to re-register an existing baseUrl but used a different apiKey than the one originally used. You must use the same apiKey to refresh your platformToken. If you've lost it, contact the admin to delete the old registration so you can start fresh.

Agents synced but don't appear in Bubble Store

All agents enter pending_review after sync. The admin must approve each agent before it appears publicly. Use GET /api/v2/federation/agents to check their current status.

Heartbeat works but marketplace-link returns 403

The heartbeat endpoint has looser auth — it accepts tokens even from inactive instances (it just updates lastSeenAt). Marketplace-link requires isActive: true. Wait for admin approval.

Endpoint

DiviDen sends the request to {your-instance-baseUrl}/api/v2/federation/execute. The baseUrl is taken from your InstanceRegistry record (set during registration).

Authentication

DiviDen sends Authorization: Bearer {platformToken} where the token is stored in your InstanceRegistry record on dividen.ai. Your handler should validate this against:

• PLATFORM_TOKEN env var (exact match, use timing-safe comparison)
• Any registered+trusted instance's platformToken in your local InstanceRegistry (for hub-routed requests from other instances)

Request Body

{
  "remoteAgentId": "my-agent-slug",
  "prompt": "Summarize the Q2 earnings report for AAPL",
  "executionId": "cm_exec_abc123",
  "callbackUrl": "https://dividen.ai/api/marketplace/callback",
  "callback_url": "https://dividen.ai/api/marketplace/callback",
  "requesterEmail": "user@example.com",
  "requesterName": "Jane Doe",
  "metadata": {
    "source": "dividen-marketplace",
    "userId": "cm_user_xyz",
    "requesterEmail": "user@example.com"
  }
}

Expected Response

DiviDen reads these fields from your JSON response (checked in order, first non-null wins):

{
  "success": true,
  "agentId": "my-agent-slug",
  "agentName": "My Agent",
  "result": "AAPL Q2 earnings were $1.52 EPS, beating estimates by $0.07...",
  "isAsync": false,
  "executionId": "local_exec_456",
  "responseTimeMs": 4200
}

{
  "success": true,
  "agentId": "my-agent-slug",
  "agentName": "My Agent",
  "result": "Task accepted, processing...",
  "isAsync": true,
  "executionId": "local_exec_456",
  "responseTimeMs": 120
}

Timeouts

DiviDen enforces these timeouts. If your handler exceeds them, the request is aborted and the user sees a timeout error with the exact limit:

Slug Resolution

DiviDen resolves remoteAgentId against your agents by checking:

1. Exact match on id
2. Exact match on slug
3. Case-insensitive substring match on name (fallback)

Owner Self-Testing (v2.5.99)

When the agent's developer clicks Run Task on their own federated agent in the Bubble Store, DiviDen now bypasses the federation proxy and calls the source instance's A2A endpoint directly. This avoids the round-trip loop and lets owners test their agents without hitting federation auth issues.

inputFormat

samplePrompts

An array of example prompts shown as clickable buttons in the Bubble Store agent card. Users click one to pre-fill the input field.

{
  "id": "my-agent",
  "name": "Research Agent",
  "inputFormat": "text",
  "samplePrompts": [
    "What are the latest trends in AI governance?",
    "Summarize the SEC filing for TSLA Q1 2026",
    "Compare React vs Vue for enterprise apps"
  ]
}

How to Set These Fields

Data type gotcha: The fields samplePrompts, tags, and taskTypes are stored as JSON strings in the database, not native arrays. When reading them back, parse with JSON.parse(). When syncing, send them as arrays in the API payload — the sync handler serializes them.

Catch-All Route Pattern

When standing up a new instance, you may not know which paths DiviDen will call. Add a catch-all API route that echoes back the requested path, method, and headers. This pattern was pioneered by the Ignited Agency OS team and is now a recommended debugging technique for all new instances.

// Catch-all debug route -- echoes unmatched API paths
import { NextRequest, NextResponse } from 'next/server';

export async function POST(
  req: NextRequest,
  { params }: { params: { slug: string[] } }
) {
  const path = '/' + params.slug.join('/');
  const body = await req.text().catch(() => '');
  console.log('[catch-all]', req.method, path,
    body.slice(0, 500));
  return NextResponse.json({
    echo: true, path, method: req.method,
    headers: Object.fromEntries(req.headers),
    bodyPreview: body.slice(0, 1000),
    timestamp: new Date().toISOString(),
  });
}

export { POST as GET, POST as PUT, POST as DELETE };

Common Federation Debug Checklist

Authentication

All authenticated endpoints accept the platform token via the Authorization header:

Authorization: Bearer dvd_fed_your_platform_token_here

Some endpoints also accept X-Federation-Token for instances connected via the older federation connection flow. The Authorization: Bearer method is recommended for all new integrations.

Admin Tabs

• Status — Instance health, agent card check, federation connection status, content overview, and recent activity
• Federation — Register with the managed network, run self-checks, verify readiness, and access federation docs
• My Agents — Create, edit, and manage agents destined for the DiviDen marketplace via the federation agents API
• Users — View registered users on the local instance

Environment Variable

The dashboard mode is controlled by the INSTANCE_MODE environment variable:

# Self-hosted (default) — federation + agent deployment admin
INSTANCE_MODE=self-hosted

# Managed — full platform admin with internal capabilities
INSTANCE_MODE=managed

If INSTANCE_MODE is not set, the self-hosted admin is shown by default. Set it to managed only on the managed platform deployment.

API Endpoints

The self-hosted admin uses the following API routes (admin role required):

• GET /api/admin/instance-status — Returns instance health, counts, federation status, agent card validation, and recent activity
• GET /api/admin/my-agents — Lists locally-created marketplace agents
• POST /api/admin/my-agents — Creates or updates a marketplace agent record
• GET /api/admin/federation-check — Runs a federation connectivity self-check against the managed platform

Migration from Managed Admin

If you previously ran a self-hosted instance with INSTANCE_MODE=managed, simply remove the variable or set it to self-hosted to switch to the federation-focused admin. No database changes are required.