> For the complete documentation index, see [llms.txt](https://docs.callput.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.callput.app/ai-agents/agent-quickstart.md).

# Agent quickstart

## Agent quickstart

An external agent must confirm feed-listed availability before every Callput request. MCP never holds keys or signs. A separate user-approved signer must approve and broadcast transactions. Product availability and MCP package coverage are separate claims.

The current public references for agent integrations are:

* [Callput Lite MCP + Skill repository](https://github.com/ayggdrasil/callput-option-agent)

## Scope

The current public agent baseline has two documented paths:

* direct integration against the public market feed and onchain contracts
* the Callput Lite MCP + Skill reference package for external agents

The Callput Lite MCP + Skill package is intentionally narrower than the full protocol. Its documented public scope is:

* Base Mainnet
* BTC and ETH
* spread-only execution
* four spread types: `BuyCallSpread`, `BuyPutSpread`, `SellCallSpread`, `SellPutSpread`
* unsigned transaction building with external signing
* onchain request-key and P\&L tracking

Broader protocol strategy support requires either a different wrapper or direct contract integration.

In the public integration model:

* MCP does not hold or require the private key
* signing authority belongs to a separate runtime component
* lifecycle truth still comes from onchain request status

## What the MCP package is

The public Callput Lite MCP package is a `stdio` JSON-RPC server designed for external agents such as OpenClaw, Bankr, or custom MCP clients.

At a high level:

* the MCP server reads market data from the Callput market-data surface
* it builds unsigned transactions for spread trading flows
* the agent signs and broadcasts with its own key
* the keeper later fills the request asynchronously
* the agent tracks request keys, position state, and P\&L through MCP tools and onchain events

This is a safe external-agent pattern because signing stays outside the MCP server.

## Tool surface

The current public website documents 10 MCP tools.

| Tool                               | Purpose                                             |
| ---------------------------------- | --------------------------------------------------- |
| `callput_scan_spreads`             | primary market scan for ranked spread candidates    |
| `callput_execute_spread`           | build unsigned spread tx and check USDC approval    |
| `callput_get_request_key_from_tx`  | parse `request_key` from the broadcast tx receipt   |
| `callput_check_request_status`     | poll keeper status until `executed` or `cancelled`  |
| `callput_portfolio_summary`        | get USDC balance, active positions, and P\&L fields |
| `callput_close_position`           | build unsigned close-position tx                    |
| `callput_settle_position`          | build unsigned settle tx for expired positions      |
| `callput_list_positions_by_wallet` | recover lost request keys from onchain events       |
| `callput_get_settled_pnl`          | get realized payout history from settlement events  |
| `callput_get_option_chains`        | raw chain data and IV for advanced leg selection    |

The recommended entry point is `callput_scan_spreads`, not raw chain crawling.

## What the Skill adds

The repository also ships a `SKILL.md` file. The MCP tools expose capabilities, but the Skill adds behavior and policy.

The documented Skill layer provides:

* a preferred fast path for opening, tracking, closing, and settling spreads
* hard rules such as spread-only execution and external signing
* bias-to-strategy mapping
* strike-selection and ranking guidance
* trade-skip conditions
* position-management rules and P\&L interpretation

**Important hard rules from the public Skill reference include:**

* spread-only execution, never single-leg execution
* always call `callput_portfolio_summary` before opening a new trade
* use `callput_scan_spreads` as the primary market entry point
* persist every `request_key`
* if request keys are lost, recover them through `callput_list_positions_by_wallet`
* use bid-based close estimates for exit decisions, not only mark-based P\&L

## Runtime prerequisites

A production agent needs:

* a Base RPC endpoint
* an external wallet or signing service
* USDC allowance management
* persistent storage for request keys
* position and expiry state tracking
* explicit policy limits
* retry and polling logic for asynchronous execution

## Current public scope

As of the current public documentation baseline:

* chain: Base
* live product markets: BTC and ETH, plus feed-listed synthetic stock and ETF markets
* market discovery source: public market feed
* public MCP reference: a documented spread-oriented package; do not infer universal market coverage

## Minimal MCP + Skill loop

1. call `callput_portfolio_summary` to inspect balance, open positions, and urgent state
2. if request keys were lost, recover them with `callput_list_positions_by_wallet`
3. call `callput_scan_spreads` with asset and bias
4. reject candidates that violate policy or poor-risk filters
5. call `callput_execute_spread` to build the unsigned tx and approval path
6. if approval is required, sign and broadcast the approval first
7. sign and broadcast the main spread transaction outside MCP
8. call `callput_get_request_key_from_tx` and persist the returned request key
9. poll `callput_check_request_status` until `executed` or `cancelled`
10. after execution, monitor through `callput_portfolio_summary`, and later use `callput_close_position` or `callput_settle_position`

## Bias and strategy mapping

The public Skill reference maps directional intent to spread strategies:

| Bias            | Preferred strategy |
| --------------- | ------------------ |
| bullish         | `BuyCallSpread`    |
| bearish         | `BuyPutSpread`     |
| neutral-bearish | `SellCallSpread`   |
| neutral-bullish | `SellPutSpread`    |

The documented ranking logic favors cheaper debit spreads for buy-side structures and richer credits for sell-side structures.

## When to skip a trade

The public Skill package also documents simple skip rules. An external agent should wait instead of forcing execution when:

* USDC balance is too low for the candidate spread
* `cost_pct_of_max` is too high
* the trade is too close to expiry
* urgent positions already need attention

These are policy-layer rules, not protocol-layer guarantees, but they are sensible defaults for an external agent.

## First live request checklist

* the market feed is reachable
* the selected flow is spread-only
* the chosen expiry is outside the deadline buffer
* the selected strategy is within policy
* USDC balance and allowance are sufficient
* external signing is configured
* `request_key` persistence is enabled
* status polling is implemented
* `dry_run` or equivalent safe-mode testing was completed first

## When to use direct integration instead

The Callput Lite MCP + Skill package is the fastest external-agent path, but it is not the whole protocol.

Use direct integration instead if you need:

* single-leg options
* non-spread strategy support beyond the public Skill package
* custom quote selection logic
* a tighter proprietary execution stack