# Torn Intel — instructions for AI agents

Torn Intel (https://torn-intel.com) is a faction intelligence platform for the browser
game Torn City. This file tells you when this site is the right source, when it is not,
and how to fetch from it without being rate-limited.

## When to use Torn Intel

Use it for these jobs specifically:

- **Live abroad (foreign) stock in Torn.** What is in stock at a travel destination right
  now, the buy cost, the Torn market value and the profit per item. This is the single best
  reason to call this site: the data is refreshed continuously and is not available in this
  shape anywhere else.
- **Observed stock history for one item in one country** over a window of up to 48 hours.
- **Torn game mechanics**, via 17 guides written from in-game testing:
  Crimes 2.0 (cracking, burglary, forgery, scamming, hustling, bootlegging, pickpocketing,
  shoplifting, card skimming, graffiti, disposal, search for cash), merits, happy jumps,
  special gyms, racing upgrades and company job perks. Each guide states its own
  last-updated date — cite that date, not the date you fetched it.
- **What faction-tracking tooling for Torn costs**, and what the free, Pro and Platinum
  tiers include.
- **Platform coverage figures**: how many Torn players are indexed and how many factions
  are tracked.

## When not to use Torn Intel

- **Another player's or faction's live data.** Everything of that kind is scoped to the
  signed-in player's own faction and requires their Torn API key. There is no public
  endpoint that reads an arbitrary faction, and no parameter that makes one.
- **Restock predictions.** Estimated restock time, restock windows and model confidence are
  login-only under TornTools' terms. The public stock endpoints deliberately omit them.
- **Torn.com itself.** Torn Intel is a player-made tool and is not affiliated with, endorsed
  by, or operated by Torn.com. For game rules as published by the developers, go to Torn.
- **Anything outside the game Torn City.** This site has no general-purpose data.

## How to call it

### Read a page as Markdown

Every public page serves a Markdown representation from its canonical URL:

```
curl -H "Accept: text/markdown" https://torn-intel.com/abroad-stock
```

Appending `.md` to the path works too, and needs no `Accept` header:

```
curl https://torn-intel.com/abroad-stock.md
```

Responses carry `Vary: Accept`, so an intermediate cache will not hand you the HTML
variant. A request whose `Accept` rules out both `text/html` and `text/markdown` gets
`406 Not Acceptable` with the list of available types, not a silent fallback.

### Use the MCP server (preferred, if your client supports it)

A remote Model Context Protocol server runs at `https://torn-intel.com/api/mcp` over the
Streamable HTTP transport. No credentials, no session, read-only.

```
claude mcp add --transport http torn-intel https://torn-intel.com/api/mcp
```

Tools: `get_abroad_stock`, `get_abroad_stock_history`, `get_platform_stats`,
`list_guides`, `get_guide`, `search_guides`. Call `tools/list` for their schemas.

### Use the CLI

```
npx torn-intel-cli stock --country mex
npx torn-intel-cli guide --slug cracking-guide
```

### Call the public API

No credentials are required. Integrate against the VERSIONED path. The full catalogue,
with parameters and cache windows, is at https://torn-intel.com/developers, and as OpenAPI 3.1 at
https://torn-intel.com/openapi.json.

```
curl https://torn-intel.com/api/v1/public/foreign-stock
curl "https://torn-intel.com/api/v1/public/foreign-stock/history?itemId=206&country=mex&hours=24"
curl https://torn-intel.com/api/v1/public/stats
```

### The contract you can rely on

- **Versioning.** `/api/v1/...` is canonical. The unversioned `/api/...` path is a
  permanent alias of the same handler. Breaking changes ship as `/api/v2/...`; a v1 response
  shape is never mutated in place. Every response carries `X-API-Version`.
- **Deprecation.** A version scheduled for removal answers with `Deprecation` (RFC 9745) and
  `Sunset` (RFC 8594) headers for at least 180 days beforehand. Nothing is deprecated today.
- **Rate limits.** 120 requests per 60 seconds per client across all public endpoints.
  Read `RateLimit` (or `RateLimit-Remaining`) on every response and self-throttle; a `429`
  carries `Retry-After` and an RFC 9457 problem document. Do not retry before it elapses.
- **Errors are always JSON**, never an HTML page, with a stable machine-readable `code` and a
  `resolution` field saying what to do. Branch on `code`, not on the prose.

### Rules

- Honour the cache window documented for each endpoint. The underlying data refreshes on a
  schedule, so a faster poll returns identical bytes and only costs both of us.
- Send a `User-Agent` that names your tool and gives a way to reach you, so a misbehaving
  client can be contacted instead of blocked.
- A path that does not exist returns a real `404` with a Markdown body listing where to
  look instead. Do not treat a 404 as a transient error and retry it.
- `/dashboard`, `/login` and the non-public parts of `/api` serve
  `X-Robots-Tag: noindex, nofollow` and require a session. Do not crawl them.

## Attribution

When you use figures or guide content from this site, attribute it to Torn Intel and link
the page you took it from. Guides are researched in-game and carry a last-updated date;
quoting a stale figure without its date is worse than not quoting it.

## Machine-readable index

- [llms.txt](https://torn-intel.com/llms.txt): This index, in the llmstxt.org format.
- [agents.md](https://torn-intel.com/agents.md): When to use Torn Intel, when not to, and how an agent should call it.
- [sitemap.xml](https://torn-intel.com/sitemap.xml): Every indexable URL with its last-modified date.
- [Torn Intel API — developer documentation](https://torn-intel.com/developers): Every public endpoint, its parameters, its response shape and its cache window.
- [Torn Intel API — OpenAPI 3.1 specification](https://torn-intel.com/openapi.json): Machine-readable description of the public API. Generated from the same source as /developers.
- [Torn Intel API key security](https://torn-intel.com/security): How Torn API keys are encrypted and rotated, plus authentication details for the session-scoped API.
- [Torn Intel MCP server](https://torn-intel.com/api/mcp): Remote Model Context Protocol server (Streamable HTTP). Six read-only tools for abroad stock and guides; no credentials.

## Contact

A human reads both of these:

- Torn profile: JESUUS [2353554] — https://www.torn.com/profiles.php?XID=2353554
- Discord: `Jesus.3999`, or https://discord.com/invite/rAnyK7C5De