# auctionhouse.fyi agent client

A standalone, read-only Rust example for price tools and plugin adapters. It calls the
public HTTP API with no credentials, validates market and item inputs, preserves null
observations, and emits JSON including a source URL. There are no game actions or uploads.

## Download and run

Install Rust (edition 2024 supported). Download this directory's files from
https://auctionhouse.fyi/developers/agent-client/ while preserving the paths:

- Cargo.toml
- Cargo.lock
- src/main.rs
- tool.json
- LICENSE

From that directory:

```sh
cargo run --locked -- forever.normal.alliance.us 14047
cargo test --locked
```

The runtime is Rust. Node tooling is not required. Exit code 0 means a successful read;
failures return code 1 and a JSON error on stderr. HTTP requests time out after 15 seconds.
429/503 responses have at most two retries, respecting Retry-After up to 60 seconds;
longer or unparseable delays stop the client for the caller to handle. 401/403 stop immediately.
Responses are capped at 2 MiB and redirects are disabled.

## Plug it into an agent

Register `tool.json` with your tool host, then invoke the compiled executable with the
validated `market` and `item` as separate arguments. Do not interpolate arguments into
a shell command. Parse stdout as JSON and treat stderr/nonzero exits as tool failures.
The supplied schema is an MCP-style tool definition, not a running MCP server.
An HTTP-capable host can instead import https://auctionhouse.fyi/openapi.json.

Present `data.row` as [unit copper price or null, quantity, observation time in Unix ms].
A null row means no observation. A null price means none listed at the last complete scan.
Never turn either into zero. 10000 copper = 1 gold. Preserve the market and variant item key.
Use `source_url` for citations and include the observation time; `data.now` is server time.
Public data is hourly. Do not call it live or claim the observed price is still executable.

See https://auctionhouse.fyi/docs/api/agents and https://auctionhouse.fyi/llms.txt.
The API is versioned at /api/v1. This example is MIT licensed; that license applies to
the example source, not a grant of rights to the game or market data. No API key needed.