> ## Documentation Index
> Fetch the complete documentation index at: https://shinydapps-bd9fa40b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VERITY

> Autonomous AI agent with 11 L402-protected services. Earns sats, pays in sats.

# VERITY

VERITY is an autonomous AI agent built on l402-kit. She sells 11 services via the L402 protocol, accumulates a Bitcoin treasury, and adjusts her own prices based on demand — without human intervention.

**Discovery endpoint:** `GET https://l402kit.com/api/verity`

***

## The 11 Services

| Service              | Endpoint                   | Base Price     | Margin |
| -------------------- | -------------------------- | -------------- | ------ |
| BTC Price            | `/api/verity/btc-price`    | 100 sats       | 100%   |
| World State          | `/api/verity/worldstate`   | 300 sats       | 100%   |
| Sentiment            | `/api/verity/sentiment`    | 300 sats       | 99.7%  |
| Web Search           | `/api/verity/search`       | 500 sats       | 90%    |
| Web Scraping         | `/api/verity/scrape`       | 500 sats       | 96%    |
| Summarize            | `/api/verity/summarize`    | 500 sats       | 99.8%  |
| Translate            | `/api/verity/translate`    | 500 sats       | 99.8%  |
| Domain Intel         | `/api/verity/domain-intel` | 2,000 sats     | 100%   |
| Research             | `/api/verity/research`     | 2,000 sats     | 97%    |
| **Alpha**            | `/api/verity/alpha`        | **5,000 sats** | 98%    |
| l402-kit Integration | `/api/verity/integration`  | 200,000 sats   | 99.9%  |

Prices are dynamic — VERITY adjusts them every 30 minutes based on demand.

***

## How to Pay

Every service follows standard L402:

```bash theme={null}
# Step 1 — request the service (get invoice)
curl -i https://l402kit.com/api/verity/btc-price

# HTTP/1.1 402 Payment Required
# WWW-Authenticate: L402 macaroon="...", invoice="lnbc..."

# Step 2 — pay the invoice with any Lightning wallet
# Step 3 — retry with proof
curl -H "Authorization: L402 <macaroon>:<preimage>" \
  https://l402kit.com/api/verity/btc-price
```

***

## Automated payment with L402Client

```typescript theme={null}
import { L402Client } from "l402-kit/agent";
import { BlinkWallet } from "l402-kit/wallets";

const client = new L402Client({
  wallet: new BlinkWallet(process.env.BLINK_API_KEY!),
  budget: { maxSats: 500 },
});

// BTC price — 100 sats
const price = await client.fetch("https://l402kit.com/api/verity/btc-price");
const data = await price.json();
console.log(data.bitcoin.usd);

// World state — 300 sats
const world = await client.fetch("https://l402kit.com/api/verity/worldstate");
const state = await world.json();
console.log(state.time.utc, state.location.city, state.weather.temperature_c);
```

***

## Service Reference

### Search — 500 sats

Web search returning top 10 organic results.

```bash theme={null}
# GET
curl -H "Authorization: L402 <token>" \
  "https://l402kit.com/api/verity/search?q=bitcoin+lightning"

# POST
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"q":"bitcoin lightning"}' \
  https://l402kit.com/api/verity/search
```

**Response:**

```json theme={null}
{
  "agent": "VERITY",
  "service": "search",
  "query": "bitcoin lightning",
  "results": [
    { "title": "...", "link": "...", "snippet": "..." }
  ],
  "paid_with": "⚡ Lightning L402"
}
```

***

### Web Scraping — 500 sats

Returns full page content as markdown.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' \
  https://l402kit.com/api/verity/scrape
```

***

### BTC Price — 100 sats

Real-time Bitcoin price in USD, EUR, and BRL.

```bash theme={null}
curl -H "Authorization: L402 <token>" \
  https://l402kit.com/api/verity/btc-price
```

**Response:**

```json theme={null}
{
  "bitcoin": { "usd": 98000, "eur": 90000, "brl": 550000 },
  "timestamp": "2026-05-10T12:00:00.000Z"
}
```

***

### Summarize — 500 sats

AI summarization up to 50,000 characters.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"...long text...", "language":"portuguese"}' \
  https://l402kit.com/api/verity/summarize
```

***

### Sentiment — 300 sats

Sentiment analysis with score, confidence, and keywords.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"Bitcoin is the future of money"}' \
  https://l402kit.com/api/verity/sentiment
```

**Response:**

```json theme={null}
{
  "analysis": {
    "sentiment": "positive",
    "score": 0.92,
    "confidence": 0.88,
    "keywords": ["bitcoin", "future", "money"]
  }
}
```

***

### Domain Intel — 2,000 sats

WHOIS, DNS records, and SSL certificates. No API key — uses public RDAP and crt.sh.

```bash theme={null}
curl -H "Authorization: L402 <token>" \
  "https://l402kit.com/api/verity/domain-intel?domain=example.com"
```

**Response:**

```json theme={null}
{
  "domain": "example.com",
  "whois": { "registrar": "...", "registered": "...", "expires": "..." },
  "dns": { "a_records": ["93.184.216.34"] },
  "certificates": [{ "issued": "...", "expires": "...", "issuer": "..." }]
}
```

***

### l402-kit Integration — 200,000 sats

Send a public GitHub repo URL. VERITY analyzes the codebase and returns complete l402-kit integration code.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/owner/repo"}' \
  https://l402kit.com/api/verity/integration
```

**Response:**

````json theme={null}
{
  "repo": "owner/repo",
  "integration": "## Detected: Express.js\n\n```typescript\nimport { l402 } from 'l402-kit';\n...",
  "next_steps": ["Apply integration code", "Set env vars", "Deploy and test"]
}
````

***

### World State — 300 sats

UTC time + caller geolocation + local weather in a single call. Zero external API cost.

```bash theme={null}
curl -H "Authorization: L402 <token>" \
  https://l402kit.com/api/verity/worldstate
```

**Response:**

```json theme={null}
{
  "time": {
    "utc": "2026-05-10T14:32:00.000Z",
    "unix": 1778421120,
    "hour": 14, "minute": 32, "weekday": "Sun"
  },
  "location": {
    "city": "São Paulo", "country": "BR", "timezone": "America/Sao_Paulo"
  },
  "weather": {
    "temperature_c": 23.4,
    "feels_like_c": 22.1,
    "humidity_pct": 68,
    "condition": "partly cloudy"
  }
}
```

***

### Research — 2,000 sats

Deep research bundle: search + scrape + AI summarization in a single call.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "bitcoin lightning network adoption 2026"}' \
  https://l402kit.com/api/verity/research
```

**Response:**

```json theme={null}
{
  "agent": "VERITY",
  "service": "research",
  "query": "bitcoin lightning network adoption 2026",
  "summary": "Lightning Network adoption has accelerated significantly in 2026...",
  "scraped_url": "https://example.com/article",
  "sources": [
    { "title": "...", "link": "...", "snippet": "..." }
  ],
  "provider": "serper",
  "paid_with": "⚡ Lightning L402"
}
```

**vs. calling services separately:** Search (500 sats) + Scrape (500 sats) + Summarize (500 sats) = 1,500 sats and 3 payments. Research costs 2,000 sats — one payment, no orchestration overhead.

***

### Alpha — 8,000 sats

Crypto-native strategy intelligence. VERITY acts as a strategist — reads cycle phase, identifies open alpha windows, and returns a concrete entry/exit plan for your capital and timeframe.

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"capital_sats": 500000, "timeframe": "7d", "risk": "medium"}' \
  https://l402kit.com/api/verity/alpha
```

**Parameters:**

* `capital_sats` — your available capital in satoshis (default: 100,000)
* `timeframe` — `"1d"`, `"7d"`, or `"30d"` (default: `"7d"`)
* `risk` — `"low"`, `"medium"`, or `"high"` (default: `"medium"`)
* `query` — optional focus area (e.g. `"Base L2 ecosystem"`)

**Response:**

```json theme={null}
{
  "agent": "VERITY",
  "service": "alpha",
  "cycle_phase": "early_bull",
  "alpha_window": "open",
  "strategy": "Farm governance tokens of new Base L2 protocols before TGE",
  "chain": "Base",
  "timeframe_days": 7,
  "entry": "TVL > $50M and governance forum activity rising",
  "exit_trigger": "TGE announced or TVL growth stalls for 48h",
  "exit_price_btc_usd": 120000,
  "position_size_pct": 20,
  "confidence": 0.74,
  "risk_level": "medium",
  "thesis": "Base ecosystem is in early growth phase. Window closes when TGE is announced.",
  "btc_price_usd": 95000,
  "sources": [{ "title": "...", "link": "..." }],
  "paid_with": "⚡ Lightning L402"
}
```

**What makes it different:** VERITY doesn't just fetch data — she synthesizes cycle context, current narratives, and market structure into a timed, actionable strategy. Intelligence without timing is just data.

***

### Translate — 500 sats

Translates text or MDX documentation to any of 11 supported languages. When `format` is `mdx`, code blocks, MDX components, URLs, and technical terms are preserved exactly — only prose is translated.

**Supported locales:** `pt`, `es`, `zh`, `ar`, `hi`, `fr`, `de`, `ru`, `ja`, `it`, `en`

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Pay once, access forever.", "locale": "pt", "format": "plain"}' \
  https://l402kit.com/api/verity/translate
```

**MDX format** (preserves code blocks and components):

```bash theme={null}
curl -X POST -H "Authorization: L402 <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "---\ntitle: Quickstart\n---\n\nPay with Lightning.", "locale": "ja", "format": "mdx"}' \
  https://l402kit.com/api/verity/translate
```

**Response:**

```json theme={null}
{
  "agent": "VERITY",
  "service": "translate",
  "locale": "pt",
  "language": "Brazilian Portuguese",
  "format": "plain",
  "translated": "Pague uma vez, acesse para sempre.",
  "source_length": 26,
  "paid_with": "⚡ Lightning L402"
}
```

Max input: 100,000 characters per call.

***

## Dynamic Pricing

VERITY adjusts prices every 30 minutes:

```
High demand (> threshold calls/hour) → price × 1.1
Zero demand (2 consecutive hours)    → price × 0.9
Floor protection                     → price never below minimum
Reputation modifier                  → success rate drives long-term adjustment
```

Each call writes to `verity_success:{service}:{hour}` or `verity_error:{service}:{hour}` in KV. The fiscal agent reads these counters daily and feeds them into the reputation module — services with high error rates get penalized, high success rates unlock better surge thresholds.

**Bonus budget reinvestment:** the fiscal agent automatically reinvests 10% of weekly revenue as consumer budget — 70% reserved for calling external L402 partners, 30% for internal service calls. VERITY earns, saves, and spends autonomously.

Check current prices at any time:

```bash theme={null}
curl https://l402kit.com/api/verity | jq '.services[].priceSats'
```

***

## Public Discovery Endpoints

These two endpoints require no L402 payment — they expose VERITY's catalog and finances for auditing and discovery.

### GET /api/verity/services

Machine-readable catalog of all active services with live pricing, floors, and surge thresholds.

```bash theme={null}
curl https://l402kit.com/api/verity/services
```

```json theme={null}
{
  "services": [
    {
      "id": "search",
      "endpoint": "https://l402kit.com/api/verity/search",
      "price_sats": 500,
      "floor_sats": 500,
      "cogs_sats": 50,
      "surge_threshold": 50
    }
  ],
  "count": 11,
  "updated": "2026-05-12T14:32:00.000Z"
}
```

Useful for agents that need to decide which service to call based on cost before committing a payment.

### GET /api/verity/fiscal

VERITY's daily fiscal report — revenue, costs, margin, and per-service breakdown. Generated at 00:00 UTC.

```bash theme={null}
curl https://l402kit.com/api/verity/fiscal
```

```json theme={null}
{
  "date": "2026-05-12",
  "agent": "VERITY",
  "revenue_sats": 8450,
  "consumer_spent_sats": 340,
  "consumer_budget_sats": 10000,
  "net_sats": 8110,
  "margin_pct": "95.98",
  "usd_equivalent": "10.00",
  "btc_usd_rate": 95000,
  "breakdown": {
    "search":    { "calls": 21, "price": 500,    "revenue": 10500, "success_rate": 98 },
    "btcprice":  { "calls": 14, "price": 100,    "revenue": 1400,  "success_rate": 100 },
    "summarize": { "calls": 6,  "price": 500,    "revenue": 3000,  "success_rate": 95 }
  },
  "generated_at": "2026-05-12T00:00:01.000Z"
}
```

Reports are stored for 7 days. Returns 404 if the day's report hasn't been generated yet.

***

## Operator API

If you fork VERITY to run your own agent, these endpoints let you change pricing and budgets at runtime — no deploy required.

All admin routes require the `DASHBOARD_SECRET` header:

```
Authorization: Bearer <DASHBOARD_SECRET>
```

### GET /api/verity/admin/config

Returns current pricing config and consumer spend for all services.

```bash theme={null}
curl -H "Authorization: Bearer <secret>" \
  https://l402kit.com/api/verity/admin/config
```

**Response:**

```json theme={null}
{
  "configs": {
    "search":  { "base": 100, "floor": 50, "surgeThreshold": 50, "cogs": 2 },
    "translate": { "base": 50, "floor": 50, "surgeThreshold": 30, "cogs": 1 }
  },
  "prices": { "search": 100, "translate": 50 },
  "consumer": { "spent_today": 340, "budget": 10000 }
}
```

### POST /api/verity/admin/config

Updates pricing parameters for a specific service. Only fields provided are changed.

```bash theme={null}
curl -X POST -H "Authorization: Bearer <secret>" \
  -H "Content-Type: application/json" \
  -d '{"service": "search", "base": 150, "floor": 80}' \
  https://l402kit.com/api/verity/admin/config
```

| Field            | Description                                      |
| ---------------- | ------------------------------------------------ |
| `service`        | Service name (required)                          |
| `base`           | Base price in sats                               |
| `floor`          | Minimum price (dynamic pricing never goes below) |
| `surgeThreshold` | Calls/hour that triggers a +10% surge            |
| `cogs`           | Cost of goods in sats (used by fiscal agent)     |

### POST /api/verity/admin/budget

Sets the consumer daily spend limit.

```bash theme={null}
curl -X POST -H "Authorization: Bearer <secret>" \
  -H "Content-Type: application/json" \
  -d '{"sats": 5000}' \
  https://l402kit.com/api/verity/admin/budget
```

Minimum: 100 sats. Changes take effect immediately.

***

## Architecture

```
VERITY (agent:shinydapps.verity)
  ├── 11 L402-protected services
  ├── Treasury: shinydapps@blink.sv
  ├── Heartbeat: every 30min (price adjustment + Satring market scan)
  ├── Query cache: KV-backed, per-service TTL (5min–24h)
  ├── Fiscal Agent: daily report at 00:00 UTC → GET /api/verity/fiscal
  ├── Service catalog: machine-readable → GET /api/verity/services
  ├── Agent contract: GET /.well-known/agent.json → verity block
  └── LAW-N: behavioral events emitted per transaction
```

VERITY is open-source — the same architecture can be forked to create your own autonomous agent.