# agent apis

Endpoints for the AI trading agent system.

## GET /api/agents-state

Fetch current agent portfolios and recent activity. This is what the frontend polls to display the Agents panel.

**Authentication**: None

**Response**:

```json
{
  "sonnet": {
    "cash": 85.50,
    "positions": [
      {
        "id": "pos_123",
        "market": "Will X happen?",
        "conditionId": "0xabcd...",
        "side": "YES",
        "shares": 50,
        "entryPrice": 0.40,
        "currentPrice": 0.45,
        "value": 22.50,
        "pnlPct": 12.5,
        "timestamp": "2026-02-28T10:00:00Z"
      }
    ],
    "totalValue": 108.00,
    "pnlPct": 8.0,
    "recentTrades": [
      {
        "action": "BUY",
        "market": "Will X happen?",
        "amount": 15.00,
        "price": 0.40,
        "reason": "Strong momentum signals...",
        "timestamp": "2026-02-28T10:00:00Z"
      }
    ]
  },
  "flash": { ... },
  "lastRun": "2026-02-28T12:00:00Z",
  "nextRun": "2026-02-28T12:30:00Z",
  "round": 142,
  "initialized": true
}
```

Behavior:

* Reads portfolios and trades from Redis
* Updates live prices by fetching current market data from Gamma API
* For positions not found in top-100 markets, does individual lookups by conditionId
* Recalculates totalValue and pnlPct with live prices
* Returns default empty state if Redis is not configured

Config: 10s max duration.

***

## GET /api/agents-run

Execute one trading round for both agents. Called by Vercel cron every 30 minutes.

**Authentication**: Requires `AGENTS_CRON_KEY` as query parameter or Vercel cron header.

```
GET /api/agents-run?key=YOUR_CRON_KEY
```

Execution flow:

{% stepper %}
{% step %}

### Fetch markets

Fetch top 20 markets (from 40 candidates, filtered).
{% endstep %}

{% step %}

### Load state

Load agent state from Redis.
{% endstep %}

{% step %}

### Update prices

Update live prices for existing positions.
{% endstep %}

{% step %}

### Auto-liquidation

Auto-liquidate positions held >48 hours (sports exempt).
{% endstep %}

{% step %}

### Build prompts

Build prompts for both agents with bankroll, positions, and market data.
{% endstep %}

{% step %}

### Call AI models

Call both AI models via OpenRouter (parallel).
{% endstep %}

{% step %}

### Parse responses

Parse JSON responses, validate actions.
{% endstep %}

{% step %}

### Execute trades

Execute up to 3 trades per agent (BUY, SELL, HOLD).
{% endstep %}

{% step %}

### Save state

Save updated state to Redis.
{% endstep %}
{% endstepper %}

Response:

```json
{
  "success": true,
  "round": 143,
  "sonnet": {
    "actions": [
      { "action": "BUY", "market": "...", "amount": 20, "reason": "..." }
    ],
    "portfolio": { "cash": 65.50, "totalValue": 108.00 }
  },
  "flash": { ... }
}
```

Constraints:

* Max 25% of bankroll per trade
* Max 3 actions per round
* 48h auto-liquidation (sports exempt)
* No crypto markets
* 500 max tokens, temperature 0.3

Config: 30s max duration. Cron: every 30 minutes.

***

## POST /api/agents-reset

Reset agent state. Clears all positions, resets bankrolls to $100.

**Authentication**: Requires `AGENTS_CRON_KEY`.

Use case: Reset the competition for a fresh start.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yesno-1.gitbook.io/yesno-docs/agent-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.