# AttaGo — Full API Reference for LLMs

## Overview

AttaGo is a serverless crypto trading dashboard providing real-time Go/No-Go
scoring for 50+ crypto assets with tiered derivatives coverage. Data refreshes
every 30 seconds for paid users.

All externally served data (dashboard, API, and data-push) uses pre-formatted
display strings and categorical labels instead of raw provider metrics. No raw
Coinglass numeric fields are externally accessible — all data is derived.

Two access modes for agents:
1. **x402 pay-per-request** — no account, payment IS authentication, business-tier data
2. **Registered account** — Cognito sign-up, tier-based subscription, alerts + webhooks

## Tiered Futures Data Model

Futures (perpetual) token coverage varies by subscription tier:

| Tier     | Futures Tokens         | Note                          |
|----------|------------------------|-------------------------------|
| Free     | Top 8 by volume        | AVAX always included          |
| Basic    | Top 16 by volume       | AVAX always included          |
| Pro      | Top 32 by volume       | AVAX always included          |
| Business | All tracked tokens     | Full coverage                 |

x402 pay-per-request always returns business-tier data (all futures tokens).
Each asset response includes a `derivSymbols` field listing which futures tokens
are covered at the requesting tier.

## x402 Payment Flow

1. Send GET request without payment header
2. Server returns HTTP 402 with PAYMENT-REQUIRED header (Base64 JSON)
3. Decode the payment requirements (price, USDC address, network, nonce)
4. Sign the payment with your wallet (EIP-712 for EVM, ed25519 for Solana)
5. Retry the request with PAYMENT-SIGNATURE header (Base64-encoded signed payload)
6. Server verifies payment via PayAI facilitator and returns data

Libraries: @x402/fetch (auto-handles 402 flow), @x402/evm, @x402/svm

## Agent Endpoints (no account required)

### GET /v1/agent/score?symbol={SYMBOL}
- Price: $0.10 USDC per request
- Auth: x402 payment only (no Cognito)
- Data tier: business (all futures tokens)
- Params: symbol (required, uppercase, 2-10 chars, e.g. BTC)
- Returns: Derived scoring data — normalized composite (0-100), GO/NO-GO/NEUTRAL signal,
  spot/perps sub-scores with component bands, categorical context labels
  (funding, positioning, OI trend, basis spread, liquidation pressure),
  market regime, derivSymbols, signalId for dedup. schemaVersion "2.0".
  No raw provider numerics — all Coinglass data is categorized into labels.
- Errors: 400 (invalid symbol), 402 (payment required), 429 (abuse ban)

### GET /v1/agent/data?symbols={SYM,SYM,...}
- Price: $0.45 USDC per request
- Auth: x402 payment only (no Cognito)
- Data tier: business (all futures tokens)
- Params: symbols (optional, comma-separated filter; default: all assets)
- Returns: Multi-asset derived response — assets keyed by symbol, each with
  composite score, spot/perps sub-scores, component bands, context labels.
  Market regime, sources, and meta hoisted to root level. schemaVersion "2.0".
- Errors: 402 (payment required), 429 (abuse ban)

### Abuse Resistance
- 5 unpaid requests in 60s -> 24h ban by IP
- 50 unpaid requests in 300s -> 48h ban by IP
- Successful x402 payment immediately clears any ban

## Agent Registration (Cognito API)

Agents can register programmatically via the Cognito API (no browser needed).
This enables subscription-based access with tier discounts, alerts, and webhooks.

### Registration Flow

1. **SignUp**: Call Cognito `SignUp` action with email + password.
   No browser or CAPTCHA required. Standard Cognito User Pool.
2. **ConfirmSignUp**: Enter the 6-digit verification code sent to the email.
   Call Cognito `ConfirmSignUp` action with the code.
3. **InitiateAuth**: Sign in with `USER_PASSWORD_AUTH` flow.
   Returns IdToken, AccessToken, and RefreshToken.
4. **Use JWT**: Include `Authorization: Bearer {IdToken}` header on all /v1/ endpoints.

Token refresh: Tokens expire in 1 hour. Use `REFRESH_TOKEN_AUTH` flow with
the RefreshToken to get new tokens without re-entering credentials.

### Subscribe to a Tier

After authentication, subscribe via `POST /v1/payments/subscribe` (x402-settled).
Subscriptions are one-time USDC purchases (not recurring billing).

### Alert + Webhook Setup for Agents

1. **Create subscription**: `POST /v1/subscriptions` with tokenId, label, and conditions
   - 25 configurable metrics (price, volume, OI, funding rate, scores, etc.)
   - OR-of-ANDs condition groups for complex alerts
   - Contradiction detection prevents conflicting alerts
   - Configurable cooldown (0–1440 min, default 5)
2. **Register webhook**: `POST /v1/user/webhooks` with HTTPS URL
   - Pro tier: up to 3 webhooks; Business: up to 10
   - Returns signing secret on creation (save it — shown only once)
   - All payloads HMAC-SHA256 signed via `X-AttaGo-Signature` header
   - Test delivery: `POST /v1/user/webhooks/{id}/test` — server-side test with retry
3. **Connect Telegram**: Send `/start` to the AttaGo bot, receive 6-digit code,
   submit via `POST /v1/user/messaging/telegram/link` — DM-only, Pro+ tier
   - List connected platforms: `GET /v1/user/messaging`
   - Disconnect: `DELETE /v1/user/messaging/telegram`
   - Test delivery: `POST /v1/user/messaging/test` (30s cooldown)
4. **Delivery preferences**: `PUT /v1/user/profile` to set preferred channels
   - Single: `email`, `push`, `webhook`, `telegram`
   - Legacy aliases: `both` (email+push), `all` (email+push+webhook)
   - Comma-separated: `email,push,webhook,telegram` (any combination)

### Webhook Payload (v2 — slim callback)

When an alert fires or resolves, AttaGo POSTs a slim JSON payload to your webhook URL.
The payload identifies which alert fired and provides a callback URL to fetch full data.
State values: `"triggered"` (criteria met) or `"resolved"` (criteria no longer met).
When resolved, a new `"triggered"` webhook fires if criteria are met again.

```
POST https://your-endpoint.com/webhook
X-AttaGo-Signature: <hmac-sha256-hex>
X-AttaGo-Event: alert
Content-Type: application/json

{
  "event": "alert",
  "version": "2",
  "environment": "production",
  "alert": { "id": "BTC#spot_score", "label": "BTC spot bullish", "token": "BTC", "state": "triggered" },
  "data": { "url": "https://api.attago.bid/v1/data/push/{requestId}", "expiresAt": "2026-03-07T12:00:00Z" },
  "timestamp": "2026-03-04T12:00:00Z"
}
```

Fetch `data.url` (no auth needed) to get full scoring data. Available 72h.
If `data.url` is null (snapshot failed), use `data.fallbackUrl` for latest public data.

Verify: `HMAC-SHA256(webhookSecret, rawBody) === X-AttaGo-Signature header`.

Retry: 3 retries with exponential backoff (1s, 4s, 16s). 5s timeout.

### Data Snapshot Retrieval

`GET /v1/data/push/{requestId}` — no auth required, requestId IS the bearer token.
Returns full derived scoring data stored at alert-fire time. 72h TTL, then 410 Gone.

## Economics Comparison

| Mode              | Cost Example             | Features                          |
|-------------------|--------------------------|-----------------------------------|
| x402 per-request  | $0.10/score, $0.45/data  | Business-tier data, no account    |
| x402 at 10 req/d  | ~$30/month               | Data only, no alerts/webhooks     |
| x402 at 480 req/d | ~$144/month              | Data only, no alerts/webhooks     |
| Business sub      | $60/month (one-time)     | 250 pushes, 150 alerts, webhooks  |
| Business + bundle | $60 + $50 = $110         | 250+800 = 1050 pushes total       |

Break-even: ~600 x402 requests/month ($60) equals Business subscription cost.
Agents making >20 requests/day should consider a Business subscription.

## MCP Server

### POST /v1/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0)
- No account required. Paid tools use x402.

Tools:
- get_asset_score(symbol) — $0.10 USDC — full data for one asset (business-tier)
- get_market_data(symbols?) — $0.45 USDC — all assets (business-tier)
- get_fear_greed() — FREE — crypto Fear & Greed index
- list_assets() — FREE — all tracked symbols with scores

Server card: https://attago.bid/.well-known/mcp/server-card.json

## Supported Chains (mainnet)

| Chain     | CAIP-2 ID                                  | USDC Contract                                |
|-----------|-------------------------------------------|----------------------------------------------|
| Base      | eip155:8453                               | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913   |
| Avalanche | eip155:43114                              | 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E   |
| Polygon   | eip155:137                                | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359   |
| Arbitrum  | eip155:42161                              | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831   |
| Optimism  | eip155:10                                 | 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85   |
| Solana    | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp   | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |

Facilitator: https://facilitator.payai.network (all chains)

## Subscription Tiers (for registered users)

| Tier     | Price     | Alerts | Refresh | Futures Tokens  | Data Pushes/mo |
|----------|-----------|--------|---------|-----------------|----------------|
| Free     | $0        | 0      | 5 min   | Top 8           | 0              |
| Basic    | $5/mo     | 5      | 30s     | Top 16          | 0              |
| Pro      | $20/mo    | 25     | 30s     | Top 32          | 75             |
| Business | $60/mo    | 150    | 30s     | All             | 250            |

Subscriptions are one-time USDC purchases (not recurring billing).
Annual pricing available at 15% discount.

## Data-Push Bundles (prepaid credits, never expire)

| Bundle | Price | Credits | Per-Push |
|--------|-------|---------|----------|
| Small  | $5    | 60      | $0.08    |
| Medium | $25   | 350     | $0.07    |
| Large  | $50   | 800     | $0.06    |

## Discovery Manifests

- OpenAPI 3.0.3: https://attago.bid/docs/openapi.yaml
- Interactive docs: https://attago.bid/docs/
- Agent manifest: https://attago.bid/.well-known/agents.json
- API catalog (RFC 9727): https://attago.bid/.well-known/api-catalog
- MCP server card: https://attago.bid/.well-known/mcp/server-card.json
- x402 payment manifest: https://attago.bid/.well-known/x402.json
- Concise summary: https://attago.bid/llms.txt