Connect your AI

The suggestion engine is not one model. It is a small set of AI providers that each answer the same request, behind one port. This page is for developers who want to add a provider, and it is honest about what exists today versus what is planned.

What exists today

A provider implements a server-side port and is registered in the engine. When a suggestion is requested, the engine asks every registered provider in parallel and merges the answers. A paid provider settles its fee through x402 from the user's Agent Wallet. There is no third-party signup yet. Providers are added in the server codebase.

If you want the full picture of how answers are merged and priced, read AI suggestions first. This page covers the contract you implement.

The provider contract

A provider is asked to price one request. The symbol is the only required input. There is no side field, because direction is an output, not a question:

// apps/server/src/suggestions/domain/suggestion.types.ts
export type SuggestionInput = {
  readonly actor: AuthenticatedUser;
  readonly symbol: string;
  readonly style?: string;     // free-form, e.g. "scalp", "swing"
  readonly strategy?: string;
  readonly marginUsd?: number;
  readonly leverage?: number;
};

A provider returns a neutral suggestion shape. The required fields are deliberately tiny, so a provider that emits only a direction and a confidence can still take part:

export type ProviderSuggestion = {
  readonly providerId: string;
  readonly side: 'long' | 'short' | 'neutral';
  readonly confidence: number; // 0 to 100
  readonly entryPrice?: number;
  readonly stopLossPrice?: number;
  readonly takeProfitPrice?: number;
  readonly reasons?: readonly string[];
  readonly risks?: readonly string[];
};

The three inputs that map to the trading parameters people ask about are already here:

• Margin is marginUsd, an optional dollar figure.
• Leverage is leverage, validated against the venue cap before any paid call.
• Trading style is style, a free-form string today. Values like scalping, day trading, and swing trading are passed straight through to your provider, which decides what they mean.

Getting paid: x402

Paid providers are settled with the x402 payment standard. Your provider quotes a price in its 402 response, and the engine drives a request, sign, retry loop that pays from the user's Agent Wallet in USDC. The payment is scoped: the engine can only pay the approved recipient, up to the user's cap, until the user's expiry. See the delegation model in self-custody.

The reference paid provider is minara, in apps/server/src/minara-client/. Its quotePrice reads the live price from the provider's 402 response, and payAndCall drives the x402 loop.

Add a provider today: checklist

• Implement the SuggestionProvider port in apps/server/src/suggestions/.
• Return a ProviderSuggestion with at least providerId, side, and confidence.
• Honor the inputs you care about: symbol always, plus style, strategy, marginUsd, leverage as you see fit.
• If you charge, expose an x402 402 quote and settle in USDC, following the minara adapter.
• Register the provider so the engine includes it in the fan-out.
• Fail loudly. A provider that errors shows up in the breakdown as failed and does not sink the request.

Planned: third-party agents and on-chain records

The goal is to let outside developers register their own agent and earn when their suggestions are used, without a code change on our side.

• Self-serve registration. [PLACEHOLDER: how an external agent signs up and receives credentials.]
• Monetization through x402. [PLACEHOLDER: how settlement flows to an outside agent builder, the payout asset and chain, and the cadence.]
• On-chain suggestion records. [PLACEHOLDER: whether a suggestion's parameters, margin, leverage, and style, are written on-chain, and the contract surface if so.]
• Quality and rate limits. [PLACEHOLDER: throughput caps, validity windows, and the quality bar an external agent must clear.]

If you are building toward this, the safest place to start is the real provider contract above. The input and output shapes are unlikely to change, and an agent that already speaks them will be close to ready.

Under the hood

• The engine and the port live in apps/server/src/suggestions/. That module owns the provider registry, the ensemble merge, the validate-before-pay gate, and the suggestion_history table.
• The reference paid provider is apps/server/src/minara-client/.
• The wallet that pays is the Agent Wallet in apps/server/src/agent-treasury/.