Skip to main content
This guide is for developers building AI agents that create trading strategies in Traseq. You’ll learn how to go from generating a strategy payload to running a backtest — all through the Public Agent API.

​
Choosing a payload format

Your agent can submit strategies in two formats:
  • SignalGraph — recommended for AI agents. It’s higher-level, easier to generate, and simpler to repair when validation fails.
  • StrategyAst — the canonical format. Use this if your agent already produces it directly.

​
Minimum scopes

For an autonomous agent that validates, writes strategies, and runs backtests, the recommended minimum scopes are:
  • workspace_read
  • strategies_write
  • backtests_write
  • backtests_read
Recommended add-ons:
  • strategies_read Useful if your agent needs to inspect existing strategies and versions.
  • system_strategies_read Useful if your agent starts from built-in templates.
  1. GET /public/v1 Read the manifest and discover the workflow contract.
  2. GET /public/v1/workspace Inspect workspace identity, API key scopes, and subscription tier.
  3. GET /public/v1/capabilities Fetch machine-readable indicators, node inputs, bindings, operators, tier limits, and validation issue shape before authoring a payload.
  4. POST /public/v1/strategies/validate Validate the draft payload and repair it until valid === true.
  5. POST /public/v1/strategies Create a draft strategy.
  6. POST /public/v1/strategies/:id/versions/finalize Promote a version to ready.
  7. POST /public/v1/backtests Queue a backtest.
  8. GET /public/v1/backtests/:id Poll until the backtest reaches a terminal state.

​
Discovering capabilities

Always call GET /public/v1/capabilities before your agent writes a strategy. This endpoint returns everything your agent needs to know about what’s supported:
  • available indicators and their parameters
  • supported node kinds and bindings for SignalGraph
  • operators, enums (timeframes, market fields, patterns)
  • plan-specific limits
  • the validation issue format (code, path, message, suggestion)
Use this as your source of truth — don’t guess indicator names or parameter shapes from prompts alone.

​
Structured validation issues

POST /public/v1/strategies/validate returns machine-readable issues. Token, AST, and graph validation issues now include:
  • code
  • path
  • message
  • suggestion
Example token issue: 
{
  "code": "WARMUP_TOO_SHORT",
  "path": "strategyAst.Strategy.warmupPeriod",
  "field": "strategyAst",
  "severity": "warning",
  "message": "Warmup setting is shorter than this strategy's inferred lookback.",
  "suggestion": "Set warmupPeriod to at least 200 for more consistent behavior when prehistory is limited or after gaps."
}
Recommended repair loop:
  1. Generate signalGraph or strategyAst.
  2. Validate.
  3. Group issues by severity.
  4. Repair the payload using code, path, and suggestion.
  5. Revalidate until blocking issues are gone.

​
cURL example

export TRASEQ_BASE_URL="https://your-traseq.example.com"
export TRASEQ_API_KEY="trsq_live_<keyId>_<secret>"

curl -s \
  -H "x-api-key: $TRASEQ_API_KEY" \
  "$TRASEQ_BASE_URL/public/v1/capabilities"

curl -s \
  -H "Content-Type: application/json" \
  -H "x-api-key: $TRASEQ_API_KEY" \
  -X POST "$TRASEQ_BASE_URL/public/v1/strategies/validate" \
  -d '{
    "signalGraph": {
      "protocol": "traseq.signal-graph",
      "version": 2,
      "nodes": [
        {
          "id": "ema_fast",
          "kind": "indicator",
          "indicator": "ema",
          "args": { "length": 20 }
        },
        {
          "id": "close_price",
          "kind": "market",
          "field": "close"
        },
        {
          "id": "cross_up_fast",
          "kind": "cross",
          "op": "cross_up",
          "left": { "ref": "close_price" },
          "right": { "ref": "ema_fast" }
        }
      ],
      "strategy": {
        "kind": "strategy",
        "entry": {
          "kind": "entry",
          "trigger": { "ref": "cross_up_fast" },
          "action": {
            "side": "long",
            "sizing": { "mode": "fixed", "value": 1 }
          }
        }
      }
    },
    "settings": {
      "maxConcurrentPositions": 1,
      "warmupPeriod": 200
    }
  }'

​
Ready-to-use assets

Two reference files are available to help you get started:
  • traseq-agent-tool-schema.json — a tool contract for the public API, ready to use with tool-enabled AI agents.
  • traseq-agent-example.ts — a minimal TypeScript client with a validate-repair loop helper.

​
TypeScript SDK example

Here’s the core pattern for building an agent client. See traseq-agent-example.ts for a full working version. 
const client = new TraseqPublicAgentClient(
  process.env.TRASEQ_BASE_URL!,
  process.env.TRASEQ_API_KEY!,
);

const capabilities = await client.getCapabilities();

const authoringPayload = await validateWithRepairLoop(
  client,
  {
    signalGraph,
    settings: {
      maxConcurrentPositions: 1,
      warmupPeriod: 200,
    },
  },
  async (currentPayload, context) => {
    return repairPayloadWithYourModel({
      capabilities,
      currentPayload,
      issues: context.issues,
    });
  },
);

const draft = await client.createStrategy({
  name: 'Agent-authored EMA breakout',
  description: 'Generated by an external AI agent',
  ...authoringPayload,
});

const ready = await client.finalizeStrategyVersion(draft.id, {
  version: draft.versions[0].version,
  ...authoringPayload,
});

const backtest = await client.runBacktest({
  strategyVersionId: ready.id,
  config: {
    timeframe: '1h',
    signalInstrument: { symbol: 'BTCUSDT' },
    initialBalance: 10000,
    execution: {
      feeModel: {
        kind: 'tiered_maker_taker',
        tiers: [
          {
            minCumulativeNotional: 0,
            makerRate: 0.001,
            takerRate: 0.001,
          },
        ],
      },
      slippage: {
        kind: 'fixed',
        unit: 'bps',
        value: 5,
      },
    },
  },
});
The key point is the strict ordering — always follow this sequence:
  1. read workspace and capabilities
  2. generate signalGraph
  3. validate
  4. repair
  5. create
  6. finalize
  7. backtest

​
Agent tool schema

Instead of giving your AI model raw HTTP access, wrap the API in a structured tool layer. See traseq-agent-tool-schema.json for the full JSON definition. Recommended tools:
  • get_manifest
  • get_workspace_context
  • get_capabilities
  • validate_strategy
  • create_strategy
  • finalize_strategy_version
  • run_backtest
  • get_backtest
Recommended validate_strategy input shape: 
{
  "type": "object",
  "additionalProperties": false,
  "required": ["settings"],
  "properties": {
    "signalGraph": {
      "type": "object",
      "description": "Preferred AI authoring payload."
    },
    "strategyAst": {
      "type": "object",
      "description": "Canonical fallback payload."
    },
    "settings": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "maxConcurrentPositions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "warmupPeriod": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "anyOf": [
    { "required": ["signalGraph"] },
    { "required": ["strategyAst"] }
  ]
}

​
Suggested system prompt

Give your AI model a system prompt that enforces the capability contract and validate-repair loop. 
You are an external AI strategy-authoring agent for Traseq.

Before composing any strategy:
1. Call get_workspace_context.
2. Call get_capabilities.
3. Use capabilities as the only source of truth for supported node kinds, bindings, indicators, operators, enums, and limits.

Authoring rules:
- Prefer signalGraph over strategyAst unless the user explicitly asks for canonical AST.
- Keep the first payload minimal and valid.
- Reuse simple, stable node ids such as close_price, ema_fast, entry_trigger.
- Do not invent unsupported fields, params, or operators.
- Do not use tokens as the primary write format.

Validation rules:
- Always call validate_strategy before create_strategy or finalize_strategy_version.
- Treat issue code, path, message, and suggestion as the repair source of truth.
- Modify the minimum subtree needed to resolve each blocking issue.
- Revalidate after every repair pass.

Execution rules:
- Create drafts before finalizing.
- Run backtests only after a ready version exists.
- Summarize backtest outcomes from summaryJson before inspecting large artifacts.

​
Repair loop template

When validation fails, repair the specific issues rather than regenerating the entire strategy. Here’s a template for a deterministic repair loop. 
Inputs:
- user_intent
- current_payload
- capabilities
- blocking_issues[]

Task:
- Return a revised payload only.
- Preserve unchanged fields.
- Modify the minimum subtree needed to resolve the listed blocking issues.

Repair policy:
1. Read each issue.code and issue.path.
2. If suggestion is present, prefer it over freeform reinterpretation.
3. Do not rename unrelated node ids.
4. Do not introduce new node kinds unless capabilities allow them.
5. Keep strategy settings unless an issue directly points to settings.

​
Tips

  • Start simple. One trigger plus one confirmation filter is much easier to repair than a complex multi-branch graph.
  • Cache capabilities. Cache the response from GET /public/v1/capabilities per workspace tier, and refresh when the subscription changes.
  • Use issue codes for repairs. Deterministic repair rules based on issue.code are more reliable than asking the model to reinterpret error messages.
  • Fix errors first, warnings second. Feed the repair loop only blocking issues initially — handle warnings in a second pass once the payload is valid.