# Tellr — Agent ATM

Full reference. Generated from the endpoint catalog. Descriptions below are the catalog text.

Live base: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/
Method: POST. Content-Type: application/json.
Price: 0.05 USDC on Base. paymentScheme: exact.

## tellr-fund-checkout

Decide how to fund a checkout before paying it. Given an exact settlement amount and the holdings you are willing to sell, returns whether it can be covered, from where (stablecoin, liquidation, or mixed), the sell legs under a 75% per-position cap, and what selling would realise as a taxable disposal. Use before an agent makes a purchase to avoid draining stablecoin. Pure decision logic: no keys, no wallet access, moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-fund-checkout
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- settlementUsd — number — required — Exact amount the checkout must receive, in USD. Required.
- stableUsd — number — optional — Stablecoin you already hold and are willing to spend. Default 0. The cheapest route — it realises nothing.
- holdings — array<object> — optional — Holdings available to sell. Each needs 'symbol', 'balanceUsd', and 'pool' ('liquidity' or 'growth'). A holding with no pool is treated as growth and will not be sold without confirmation.
  - symbol — string — optional — Token symbol, e.g. BAG
  - balanceUsd — number — optional — Position value in USD
  - pool — "liquidity" | "growth" — optional — liquidity or growth
  - change7dPct — number — optional — 7-day move in percent, used for ranking
- deadlineMs — integer — optional — Milliseconds you have before the checkout times out. Echoed back with a quote-risk flag.
- sourceOrder — "stablecoin_first" | "liquidity_first" — optional — stablecoin_first (default) spends stablecoin before selling. liquidity_first sells holdings even when stablecoin is available — for deliberate rebalancing.
- maxLiquidationUsd — number — optional — Per-purchase cap on how much may be sold to cover one checkout. Default 250. Above this the call is denied outright.
- minTransferUsd — number — optional — Dust floor. Default 1. A shortfall below this is too small to be worth moving and is skipped.
- txCeilingUsd — number — optional — Per-transaction ceiling to evaluate against. Default 150.
- dailyCapUsd — number — optional — Daily cap to evaluate against. Default 500.
- voiceConfirmed — boolean — optional — Whether a human has explicitly confirmed. Default false.

### Output

- ok — boolean — optional — Transport-level success
- action — "fund" | "confirm_required" | "deny" | "skip" — optional — fund (coverable) | confirm_required (needs a human) | deny (refused) | skip (nothing to do)
- reason — string — optional — Rule that produced the answer, e.g. within_limits, liquidation_over_per_purchase_cap, growth_requires_confirm, below_min_transfer
- settlementUsd — number — optional — The amount the checkout needed
- funding — object — optional — How the checkout would be covered
  - source — "stablecoin" | "liquidation" | "mixed" — optional — stablecoin | liquidation | mixed
  - raisedUsd — number — optional — Total raised by selling. 0 means nothing was sold.
  - coveredUsd — number — optional — Total value the routes cover
  - coversCheckout — boolean — optional — True when covered >= settlement
  - legCount — integer — optional — Number of sell legs
  - realisesPnl — boolean — optional — True when selling crystallises a gain or loss
  - netRealizedPnlUsd — number — optional — Signed net realised P&L. Negative is a loss. Null when cost basis is unknown.
  - disclosesRealizedLoss — boolean — optional — True when this funding would crystallise a loss
- plan — object — optional — Sell plan when liquidation is needed, else null. legs[] each carry symbol, sellUsd, balanceUsd, pool and note.
  - legs — array<object> — optional — One entry per position to sell
  - totalSellUsd — number — optional — Sum of all legs
  - perPositionCapFraction — number — optional — 75% cap applied per position
- deadlineRisk — string — optional — quote_required_at_execution when a deadline was supplied — the plan must be re-quoted inside the window
- language — string — optional — Always 'descriptive_only'. This is a description of an amount, not an authorisation to move funds.
- disclaimer — string — optional — States explicitly that this is not an authorisation and that the caller applies its own limits and confirmation.
- stableUsd — number — optional — Stablecoin the caller said was available.
- stableAppliedUsd — number — optional — Stablecoin actually applied to this checkout.
- liquidationRequiredUsd — number — optional — Portion that would have to come from selling.
- sourceOrder — "stablecoin_first" | "liquidity_first" — optional — Order used: stablecoin_first (default) or liquidity_first.
- deadlineMs — integer — optional — The caller's deadline, echoed back.

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-fund-checkout \
  -H 'Content-Type: application/json' \
  -d '{"settlementUsd":20,"stableUsd":6,"holdings":[{"symbol":"EXAMPLE","balanceUsd":100,"pool":"liquidity"}]}'
```

### Verdicts

`action` is one of:
- fund
- confirm_required
- deny
- skip

## tellr-check

Decide whether a spend can auto-execute, needs a human, or must be refused, against configured per-transaction ceilings, a daily cap and pool rules. Returns one of three fixed verdicts with the rule that produced it. Pure decision logic: no keys, no wallet access, moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-check
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- amountUsd — number — required — The spend being evaluated. Required.
- dailySpentUsd — number — optional — Already spent today. Default 0.
- pool — "liquidity" | "growth" — optional — liquidity or growth. Growth always requires confirmation.
- voiceConfirmed — boolean — optional — Whether a human has confirmed. Default false.
- txCeilingUsd — number — optional — Per-transaction ceiling. Default 150.
- dailyCapUsd — number — optional — Daily cap. Default 500.
- faceMatchFailed — boolean — optional — Forces confirmation even under the ceiling.

### Output

- ok — boolean — optional
- decision — "allow" | "confirm_required" | "deny" — optional — allow | confirm_required | deny
- reason — string — optional — e.g. within_limits, over_tx_ceiling, over_daily_cap, growth_pool_requires_confirm
- details — object — optional — The inputs used, so the answer is auditable

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-check \
  -H 'Content-Type: application/json' \
  -d '{"amountUsd":20,"pool":"liquidity","dailySpentUsd":35}'
```

### Verdicts

`decision` is one of:
- allow
- confirm_required
- deny

## tellr-sell-plan

Build a descriptive sell plan that raises a target amount from a set of holdings. Sells stablecoins first, then smaller liquidity positions, and caps every position at 75% so no single holding is emptied. Returns legs and reasoning only — it does not execute and does not predict prices. Pure decision logic: no keys, no wallet access, moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-sell-plan
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- targetUsd — number — required — Amount to raise. Required.
- holdings — array<object> — optional — Positions available. Each needs symbol, balanceUsd and pool.
  - symbol — string — optional
  - balanceUsd — number — optional
  - pool — "liquidity" | "growth" — optional
  - change7dPct — number — optional — 7-day move, used for ranking
- rankBy — "drawdown7d" | "balance" — optional — drawdown7d (default) or balance
- tagMap — object — optional — Optional map of symbol to pool when holdings carry no pool field
- voiceConfirmed — boolean — optional — Required to include growth-pool holdings. Default false.
- txCeilingUsd — number — optional
- dailyCapUsd — number — optional

### Output

- ok — boolean — optional
- legs — array<object> — optional — One leg per position: symbol, sellUsd, balanceUsd, pool, note
- totalSellUsd — number — optional
- perPositionCapFraction — number — optional — 0.75
- needsGrowthConfirm — boolean — optional — True when growth holdings are required and unconfirmed
- language — string — optional — Always 'descriptive_only'
- disclaimer — string — optional — Figures describe recent market data only. Not a prediction or recommendation.
- shortfallUsd — number — optional — Amount the plan could NOT raise. Non-zero means the target is unreachable under the 75% cap.
- rankNote — string — optional — One-line statement of the ordering rule used, so a caller never has to infer it.
- rankingConfidence — string — optional — Truth contract for the ordering. Currently 'balance_tiebreak_only' — the order is a defined liquidity waterfall, NOT a performance ranking.
- reservedAvailable — array<object> — optional — reserved-pool bags present but never sellable, reported so they are not silently dropped.

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-sell-plan \
  -H 'Content-Type: application/json' \
  -d '{"targetUsd":20,"holdings":[{"symbol":"EXAMPLE","balanceUsd":100,"pool":"liquidity"},{"symbol":"EXAMPLE","balanceUsd":40,"pool":"growth"}]}'
```

## tellr-privilege-audit

Audit a privilege-affecting event before honouring it. Blocks privilege escalation that arrives as a gift, airdrop or unsolicited NFT — possession alone is never authority, an explicit user action is required. Pure decision logic: no keys, no wallet access, moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-privilege-audit
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- type — string — required — Event type, e.g. session_key_expand. Required.
- source — string — optional — Where it came from, e.g. unsolicited_nft_gift
- explicitUserAction — boolean — optional — Whether the user explicitly acted. Default false.

### Output

- ok — boolean — optional
- allowed — boolean — optional — Whether the event may be honoured
- decision — string — optional
- reason — string — optional — e.g. privilege_change_from_gift_blocked
- rule — string — optional — e.g. explicit_user_action_required
- type — string — optional — The privilege event type that was audited, echoed back.
- source — string — optional — Where the event came from, e.g. unsolicited_nft_gift.

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-privilege-audit \
  -H 'Content-Type: application/json' \
  -d '{"type":"session_key_expand","source":"unsolicited_nft_gift","explicitUserAction":false}'
```

## tellr-classify

Classify a holding as liquidity or growth for policy purposes. Untagged holdings FAIL CLOSED to growth, the pool that requires confirmation, so missing information never becomes a permissive default. Pure decision logic: no keys, no wallet access, moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-classify
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- symbol — string — required — Token symbol. Required.
- declaredPool — "liquidity" | "growth" | "reserved" — optional — Caller's declaration, honoured if present. Three pools: liquidity (spendable, 75% cap), growth (sellable only with an explicit confirm), reserved (committed to a job - never sellable at any amount). An unrecognised value is refused, never coerced to liquidity.
- tagMap — object — optional — Optional symbol-to-pool map
- liquidityWhitelist — array<string> — optional — Optional symbols to treat as liquidity

### Output

- ok — boolean — optional
- symbol — string — optional
- pool — "liquidity" | "growth" | "reserved" — optional — liquidity or growth
- reason — string — optional — e.g. declared, manual_tag, default_growth_fail_closed

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-classify \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"EXAMPLE","declaredPool":"liquidity"}'
```

## tellr-top-off

Decide whether a card top-off is worth making toward a target balance, and whether limits allow it. Once the card is at or above target it returns skip, so it is idempotent and self-limiting. Shortfalls below the dust floor are skipped rather than requested. Describes an amount — it is not an authorisation and moves nothing.

URL: https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-top-off
Method: POST, Content-Type: application/json
Price: 0.05 USDC on Base
Payment: HTTP 402 Payment Required on unpaid; 200 after settlement.

### Input

- cardBalanceUsd — number — required — Current card balance. Required.
- targetUsd — number — optional — Balance to top up toward. Default 50.
- enabled — boolean — optional — Opt-in flag. Default false; without it the call returns skip.
- minTransferUsd — number — optional — Dust floor. Default 1.
- dailySpentUsd — number — optional
- txCeilingUsd — number — optional — Default 150
- dailyCapUsd — number — optional — Default 500
- voiceConfirmed — boolean — optional

### Output

- ok — boolean — optional
- action — "request" | "confirm_required" | "deny" | "skip" — optional — request | confirm_required | deny | skip
- reason — string — optional — e.g. within_limits, at_or_above_target, top_off_disabled, below_min_transfer
- amountUsd — number — optional — The top-off amount, or 0 when skipped
- cardBalanceUsd — number — optional
- targetUsd — number — optional
- language — string — optional — Always 'descriptive_only'
- disclaimer — string — optional — States that this is not an authorisation to move funds.
- enabled — boolean — optional — The opt-in flag as the engine read it. False yields action 'skip'.
- targetSource — "owner" | "derived" | "default" — optional — Where the target came from: owner (caller-supplied targetUsd always wins), derived (computed from a supplied report), or default (package floor).
- note — string — optional — Short human-readable note on the decision.

### Example

```
curl -X POST https://x402.bankr.bot/0xcdc493fb6f0fa17b213ac2195bc454b39c1228ec/tellr-top-off \
  -H 'Content-Type: application/json' \
  -d '{"cardBalanceUsd":15,"targetUsd":20,"enabled":true}'
```

### Verdicts

`action` is one of:
- request
- confirm_required
- deny
- skip

## Shared conventions

An unpaid POST returns HTTP 402 Payment Required. The PAYMENT-REQUIRED header carries the x402 challenge. Settle that challenge in USDC on Base, then retry the same POST with the payment payload. A 200 is the decision, and it arrives only after settlement.

Responses are JSON. `ok: true` means the call was accepted and parsed. It is not permission to move funds. Read `decision` or `action`.

Where a response carries `language`, the value is `descriptive_only`. The body describes an amount or a plan. It is not an authorisation and it does not execute.

Disclaimer strings, as the catalog defines them:
- tellr-fund-checkout — States explicitly that this is not an authorisation and that the caller applies its own limits and confirmation.
- tellr-sell-plan — Figures describe recent market data only. Not a prediction or recommendation.
- tellr-top-off — States that this is not an authorisation to move funds.

tellr-classify fails closed. An untagged holding returns pool `growth`. Missing information never becomes a permissive default. `growth` does not auto-sell. `reserved` is not sold.

tellr-check returns exactly one of `allow`, `confirm_required`, `deny`. Those are the verdict. They are not suggestions.

tellr-sell-plan returns legs and a shortfall. It does not return a spend verdict. A plan is not permission to sell. The spend verdict is tellr-check.

A future `vectors` list of fixed inputs and expected outputs can be added beside these files without changing the fields above.