FAQ

This page is intentionally long. If you’re stuck on a specific step, start with Quickstart (5 minutes).

General

Is this trading advice? No. Sentiment402 provides market context for automation and research only.

What does Sentiment402 actually return? Structured JSON snapshots (global, crypto, TradFi, or asset-focused) with sentiment + narrative context. See Introduction and Response Schema.

What’s the difference between “global snapshot”, “pulse”, and “asset view”?

  • Global: both crypto + TradFi plus correlation and data quality fields.

  • Pulse: the core domain pulse (crypto or tradfi) plus movement/quality metadata.

  • Asset view: a ticker-focused narrative list for a single symbol.

How often is data updated? Snapshots are generated hourly. Use generatedAt (and windowStart/windowEnd on the global snapshot) as the source of truth for freshness.

What does “freshness” mean in practice? The API is designed around hourly windows; polling every few minutes is usually wasteful (and costs money). Most integrations either:

  • Poll hourly (or every 10–30 minutes if you want to react quickly to the new hour), or

  • Cache locally and only refresh on a schedule.

Do you return raw X posts? No. We strictly adhere to platform ToS. We provide synthesized summaries and references (IDs/links) rather than raw content.

What is "WSB Heat"? It tracks r/wallstreetbets activity separately from serious TradFi sentiment. It's capped at 10% influence to prevent meme-stock noise.

Which symbols/tickers are supported for :symbol? Supported symbols are curated. If you request an unsupported symbol, you’ll get 404 with UNSUPPORTED_TOKEN. If you’re unsure, start with common symbols (e.g. BTC, ETH, SOL, SPY, QQQ, NVDA) or contact support.

Pricing & Payment

How much does it cost? $0.02 per request (20,000 micro-USDC).

What counts as a “paid request”? Generally, the successful “paid retry” that returns 200 is billable. You’ll often see an initial 402 challenge first, which is part of the x402 flow.

Do I need a subscription? No. Pay per request using your wallet.

Do I need an account / API key? No API keys for paid access. Payment is done via x402 signatures.

Which network should I use? Use v2 if you want to pay on Base or Solana. Use v1 only for legacy Base/EVM clients.

What’s the difference between v2 and v1 payments?

  • v2 uses PAYMENT-REQUIRED / PAYMENT-SIGNATURE headers and may offer multiple accepts[] options (Base + Solana).

  • v1 uses legacy header names (e.g. X-PAYMENT, X-PAYMENT-REQUIRED) and is Base/EVM-only.

Can I be charged if I send a bad request? Treat “paid retries” as billable work. Validate your URL and parameters (and consider using /discovery/resources) before automating retries.

Can I choose Base vs Solana on v2? Yes. The 402 payment requirements include one or more payment options; your client selects which option to sign.

Technical

What is x402? A protocol for HTTP micropayments using the 402 Payment Required status code.

Do I need a Coinbase account? No, just a wallet with USDC.

Why do I see a 402 but the response body is empty? Some HTTP clients, proxies, or middleware may strip bodies on 402. The robust approach is:

  • Read the PAYMENT-REQUIRED header and decode it (e.g. with @x402/core/http), then

  • Sign the decoded requirements and retry.

What headers do I need to handle?

  • v2:

    • PAYMENT-REQUIRED (server → client, challenge)

    • PAYMENT-SIGNATURE (client → server, signed payment)

    • PAYMENT-RESPONSE (server → client, settlement proof; optional to consume)

  • v1 (legacy):

    • X-PAYMENT-REQUIRED (server → client)

    • X-PAYMENT (client → server)

    • X-PAYMENT-RESPONSE (server → client)

Do I need to decode PAYMENT-REQUIRED if the body is present? Not strictly, but decoding the header is more robust. Treat the header as canonical.

Should I retry automatically on 402? Yes, but only after you’ve validated:

  • You’re calling the endpoint you intended

  • Your query parameters are correct

  • You’re choosing the right payment option (Base vs Solana on v2)

Then implement the “challenge → sign → retry once” pattern.

Are there rate limits? Yes. Rate limiting is enforced to prevent abuse. If you see 429, back off and retry after retry_after.

What should I do when rate limited (429)?

  • Use the retry_after value from the response.

  • Implement exponential backoff and local caching.

  • Avoid retrying paid calls in tight loops.

How do I handle caching? Snapshots are generated hourly and cached. You should implement local caching appropriate to your use case to avoid redundant paid calls.

What is the “compact trading” format? A smaller payload intended for bots and loops. Request it with:

?format=compact_trading

You can also request a projection with:

&fields=ts,mood,rec

See the allowlist in Endpoints.

Why does format=full not work? Full format is the default. Omit format to receive the full response.

Can I use fields without format=compact_trading? No. fields is only meaningful for compact mode.

Why does the compact format contain signals that look like tickers? In compact mode, signals is a small set of “what’s in focus” identifiers (often tickers) intended to be easy to consume in trading logic.

What errors should I expect?

  • 402: payment required (challenge/response)

  • 400: invalid query (INVALID_FORMAT, INVALID_COMPACT_FIELDS)

  • 404: unsupported symbol (UNSUPPORTED_TOKEN)

  • 429: rate limited

  • 503: snapshot not ready (SNAPSHOT_NOT_READY)

Do v1 and v2 return different JSON? No; the payloads are the same shapes. The difference is primarily payment/header behavior and which networks can be used to pay.

Is there a machine-readable API reference? Yes: GET /discovery/resources returns metadata including schemas and pricing.

Security & Privacy

Do you ever need my private key? No. You sign x402 challenges locally; your private key should never be sent to Sentiment402.

What do you log? Like most APIs, basic request/response metadata may be logged for reliability, abuse prevention, and debugging. Don’t send secrets or personal data in query params.

Can I use this from a browser? Yes, but you must be able to read the PAYMENT-REQUIRED header in fetch. The API exposes the payment headers via CORS for versioned endpoints.

If a browser environment prevents you from safely storing a key, run payments server-side and proxy the data you need to your client.

Reliability

What if the snapshot isn’t ready yet? You may receive 503 with SNAPSHOT_NOT_READY. Retry with backoff.

Will the schema change? The API follows an additive-first approach; new fields may appear over time. Use tolerant JSON parsing and avoid strict “no unknown fields” assumptions unless you control the full schema validation.

Support

Where can I get help? Email: [email protected]

How do I report a bug? Include:

  • The endpoint path (e.g. /v2/snapshot/crypto)

  • Your query string (e.g. format=compact_trading&fields=...)

  • The HTTP status and error body

  • A timestamp (UTC) for when the issue occurred

PreviousUse cases

Last updated