Trade Eyes API & Widget Integration

1. Create a temporary widget session

Configure the exact HTTPS origin of your partner site in organization settings. Your authenticated server determines the customer’s stable, opaque identifier; do not use an email address. endUserId is required when your organization has a per-user daily cap.

// Run on your partner server, after authenticating your customer.
// Read brokerApiKey from your server's secret store.
const response = await fetch(
  'https://tradeeyes.app/api/public/business/v1/sessions',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + brokerApiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      origin: 'https://partner.example',
      endUserId: authenticatedCustomer.internalId
    })
  }
);
if (!response.ok) throw new Error('Session could not be issued');
const session = await response.json();
// Return session to this customer only, with Cache-Control: no-store.
// { token, expiresAt, name, disclaimer }
// Never return brokerApiKey or accept a customer ID without verifying it.

Sessions expire after ten minutes. Revoking the issuing key invalidates its sessions. After expiry, destroy the old widget, issue a new session from your server and mount again. Protect your own session endpoint against cross-site requests and unauthorized access.

2. Embed AI Trade Idea on your website

<script src="https://tradeeyes.app/business-widget.js"></script>
<div id="trade-eyes"></div>
<script>
async function mountAssistant(brokerMarketData) {
  // Implement this authenticated endpoint on YOUR website.
  // It runs the server-side session request shown above.
  const response = await fetch('/your-api/trade-eyes-session', {
    method: 'POST',
    credentials: 'same-origin'
  });
  if (!response.ok) throw new Error('Cannot open chart assistant');
  const session = await response.json();
  const target = document.getElementById('trade-eyes');
  if (!target) return;
  const widget = TradeEyes.mount(target, {
    sessionToken: session.token,
    name: session.name,
    marketData: brokerMarketData
  });
  return widget;
}
// Supply real candles from your authorized feed:
// const widget = await mountAssistant(currentMarketData);
// On instrument changes: widget.updateInstrument(nextMarketData);
// On page teardown or before remounting: widget.destroy();
</script>

marketData uses the same candle contract as the instrument endpoint below. Without candles, the widget shows a chart-image upload. updateInstrument replaces evidence; it does not trigger a paid analysis automatically. The customer starts each review explicitly.

The SDK currently creates its sandboxed iframe at https://tradeeyes.app/business-widget and sends the session through a target-origin message. Allow scripts and frames from tradeeyes.app in your website’s content security policy. The widget validates the parent origin; never bypass that check. Organization branding and disclaimer are verified server-side.

3. Analyze your instrument data or a chart image

// Partner server: brokerCandles contains 30–500 real candles.
const requestId = crypto.randomUUID();
const response = await fetch(
  'https://tradeeyes.app/api/public/business/v1/instrument',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + brokerApiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requestId,
      endUserId: authenticatedCustomer.internalId,
      lang: 'en',
      plan: null,
      marketData: {
        symbol: 'EURUSD', timeframe: '1h', currency: 'USD',
        asOf: sourceTimestamp,
        candles: brokerCandles
      }
    })
  }
);
const job = await response.json();
// POST: { jobId, status, result } or { jobId, status, error }
// Keep requestId for network retries; don't mint a new ID on every retry.

Send 30–500 chronologically ascending candles with unique ISO timestamps. Each candle has timestamp, open, high, low, close and volume (number or null). Include symbol, timeframe, currency and asOf. Data comes from your feed, not an independent Trade Eyes live feed.

// POST /analyze, with the same server Authorization header
{
  "requestId": "REPLACE_WITH_NEW_UUID",
  "image": "data:image/png;base64,REPLACE_WITH_CHART_DATA",
  "plan": null,
  "lang": "en",
  "endUserId": "customer_42"
}

Images must be valid PNG, JPEG or WebP and no larger than 8 MB decoded. plan is required and may be null; a supplied plan contains side, entry, stop, target, quantity, equity and rationale. Requests made with a widget session also require X-Trade-Eyes-Parent-Origin matching its approved origin; the widget handles this for you.

4. Read results and handle running jobs

A completed POST returns jobId, status and result. A repeated requestId for a running job returns HTTP 202; poll the status endpoint with bounded backoff until the job succeeds or fails. A retry with the same request ID is deduplicated and must use the same credential and session context.

const response = await fetch(
  'https://tradeeyes.app/api/public/business/v1/status?id=' + jobId,
  { headers: { Authorization: 'Bearer ' + brokerApiKey } }
);
if (!response.ok) throw new Error('Result unavailable');
const job = await response.json();
// GET: { id, status, result, created_at, finished_at }
// status: running | succeeded | failed
// Use the same server key that created the job.
// A widget session can only read jobs created within that session.

Instrument results include computed market evidence, AI interpretation, limitations, numeric plan checks, policyVersion, language, disclaimer and configured actions. Treat WAIT, missing evidence and human-review flags as meaningful outcomes. Never present a numeric policy pass as regulatory approval or a probability of profit.

AI Trading Coach: import company trade evidence

Create an account and versioned risk mandate in your organization workspace first. The risk endpoint requires a permanent server key and active Risk access—not a widget token.

// POST /risk with Authorization and Content-Type: application/json
{
  "requestId": "REPLACE_WITH_NEW_UUID",
  "accountId": "REPLACE_WITH_ORGANIZATION_ACCOUNT_UUID",
  "source": "Partner trade export",
  "rows": [{
    "trade_id": "trade-1",
    "timestamp": "2026-10-22T09:00:00Z",
    "symbol": "BTCUSD", "currency": "USD", "pnl": -50,
    "equity_before": 10000, "entry": 60000,
    "stop": 59000, "quantity": 0.05
  }]
}

Up to 2,000 rows per request. Duplicate trade IDs within the supplied account history are rejected. The response contains jobId, status and result; result contains recordId and report. Review it in the team workspace. The status endpoint requires Broker access, so Risk-only integrations should read the returned report or the team workspace rather than rely on status polling. Calculations use imported equity, linear units and UTC days; missing evidence is unassessed, not silently passed. No live broker synchronization or automatic account restrictions are provided.

Languages, daily limits & partner buttons

• Language: use a supported locale such as en or id on direct analysis requests; otherwise the organization default applies. The widget uses the organization default, not a mount-level lang option.
• Daily limit: configure an organization per-user cap and pass a stable endUserId when creating a session or sending a direct analysis request. Identifiers are hashed for stored usage; daily counters follow UTC.
• Result buttons: configure up to three HTTPS links in organization settings. Supported placeholders are symbol, timeframe, side, entry, stop and target. Symbol and timeframe come from submitted candles; plan placeholders come from a supplied plan, not guaranteed AI-generated trade levels. Missing values become empty strings.

https://partner.example/order?symbol={symbol}&timeframe={timeframe}

Trade Eyes does not execute orders. Keep customer authentication, suitability, order confirmation and all trading permissions on your own platform.