# Piteas (app.piteas.io) — LLM & agent context

> Primary human documentation: https://docs.piteas.io/piteas-sdk-api  
> Contracts & router details: https://docs.piteas.io/contracts (verify on-chain; docs beat this file if they diverge)

This file summarizes how builders and automated agents should integrate with **Piteas**—PulseChain’s DEX aggregator stack—and where to read authoritative specs. It is **not** a substitute for the docs; rate limits, addresses, and payloads may change.

---

## Product model (high level)

- Piteas uses an **off-chain pathfinding** model: routes are resolved off-chain; the service returns **call data** for on-chain execution (not “routing exclusively via repeated on-chain simulation” in the classical sense).
- Quote/router responses are produced for **Piteas main app**, **widget**, and **approved partner** integrations—not as open infrastructure for unconstrained high-frequency quoting.
- Piteas does **not** operate a dedicated public RPC for integrators: quote work assumes **native PulseChain RPC** and Piteas-side algorithms. **Request volume must stay within published limits** (see below).

## When the public quote API is / is not appropriate

- **Suitable:** product-facing integrations (dapp, widget, partner flow) with **moderate, bounded** quote traffic and clear user context.
- **Not suitable (stated in docs):** e.g. **arbitrage or high-frequency bot** style usage at this stage—expect throttling, blocks, or access review.

## Getting formal API / partnership access

If you need sustained or elevated access, docs describe contacting the team (e.g. **Telegram / X**) with:

- Short description of the product
- Expected **request rates** (daily / hourly / per minute)
- If a **portal** integration: approximate **user count**

This is a **policy / business** step, not a self-serve key rotation (see official page for current process).

---

## Piteas SDK / public quote API (beta)

- **Status:** **Beta**—errors and behavior may change; always handle **429 / 5xx** and treat limits as strict.
- **Base URL (quote):** `https://sdk.piteas.io`
- **Monorepo (Basic + Advanced examples, integration surface):**  
  https://github.com/piteasio/piteas-api-monorepo

### HTTP: `GET /quote`

**Full URL pattern:** `https://sdk.piteas.io/quote?...`

#### Query parameters (authoritative list in docs)

| Parameter          | Required | Type   | Notes |
|--------------------|----------|--------|--------|
| `tokenInAddress`   | yes      | string | E.g. contract `0x…` or literal **`PLS`** for native |
| `tokenOutAddress`  | yes      | string | Same as above |
| `amount`           | yes      | integer| **Raw amount including decimals** (wei-style integer, not human float) |
| `allowedSlippage`  | yes      | float  | Docs default example **0.5** (percent-style as documented) |
| `account`          | no       | string | Receiver; defaults conceptually to **msg.sender** if omitted |

**Example (from docs, illustrative):**  
`GET https://sdk.piteas.io/quote?tokenInAddress=PLS&tokenOutAddress=0xefD766cCb38EaF1dfd701853BFCe31359239F305&amount=1000000000000000000000000&allowedSlippage=0.50`

### Successful response (conceptual fields)

A typical **200** JSON includes (names may match SDK typings in the monorepo):

- **`srcToken` / `destToken`:** address, symbol, decimals, `chainId` (PulseChain **369** in examples)
- **`srcAmount` / `destAmount`:** hex strings for amounts as returned
- **`gasUseEstimate`**, **`gasUseEstimateUSD`:** planning hints (still validate locally)
- **`methodParameters`:**  
  - **`calldata`** — contract call data for the router  
  - **`value`** — native value to send with the tx (hex), when applicable
- **`route`:** `paths`, `swaps` — human/debug routing structure; treat as **diagnostic**, not the execution primitive (execution is **`methodParameters`**).

**Execution rule (from docs):** To perform the swap, send a transaction **to the Piteas router contract** using **`methodParameters.calldata`**, set **`value`** from **`methodParameters.value`** when non-zero, and align **gas / slippage / deadlines** with your app’s safety checks. **Read the router ABI and docs**—encoded arguments match on-chain expectations.

Illustrative **ethers.js** pattern from docs:

```js
const tx = await signer.sendTransaction({
  to: '<PITEAS_ROUTER_ADDRESS_FROM_DOCS>',
  value: quote.methodParameters.value,
  data: quote.methodParameters.calldata,
})
```

Replace `<PITEAS_ROUTER_ADDRESS_FROM_DOCS>` with the current **PiteasRouter** address from https://docs.piteas.io/contracts (docs historically showed `0x6BF228eb7F8ad948d37deD07E595EfddfaAF88A6`—**verify before production**).

### Error semantics (integrators must handle)

| HTTP | Meaning (per docs) |
|------|---------------------|
| **429** | **Rate limit**—docs: **max ~10 requests per minute** in beta; exceeding may yield **~1 hour block** from SDK manager |
| **500** | Pathfinder / server unable to resolve route; retry policy should be conservative |
| **403** | Possible IP block / abuse signal—contact team if unexpected |

Always backoff, jitter retries, and **never** spin tight loops against `/quote`.

---

## Rate limits & operational hygiene (beta)

- Treat **10 requests / minute** as a **hard ceiling** unless you have written approval for more.
- Cache quotes client-side where UX allows; debounce UI-driven refreshes.
- Do **not** ship integrations that share one IP across many silent bots—risk of **403** and harm to other users.

---

## Querying documentation programmatically (agents)

Some pages support **natural-language follow-up** against the doc corpus via HTTP GET with an **`ask`** query parameter on the **Markdown** variant of the page. Pattern described on the SDK/API doc page:

```http
GET https://docs.piteas.io/piteas-sdk-api.md?ask=<url-encoded-question>
```

Use this when you need clarification beyond a single crawled HTML snapshot. Keep questions **specific and self-contained**.

---

## This web app (app.piteas.io)

- **User-facing SPA** for swap and related flows; **not** the quote API host (`sdk.piteas.io` is separate).
- **Sitemap:** `https://app.piteas.io/sitemap_index.xml`
- **robots:** `https://app.piteas.io/robots.txt`

For **integration**, prioritize **docs + monorepo** over scraping the SPA.

---

## Maintenance

- Last harmonized with public documentation page: **Piteas SDK/API** — https://docs.piteas.io/piteas-sdk-api  
- If anything here conflicts with **docs.piteas.io** or on-chain config, **trust docs and chain state**.