Common Use Cases

Use this page when you already know the job to be done, but do not yet know which AgentQL surface should own it.

Each section maps one common integration scenario to the best surface and starting page.

1. Show the latest token price in a web app

• Best surface: Market API price snapshot
• Start page: Use HTTP
• Why: one request-response lookup with a clean network trace.

GET /v1/market/price-snapshot?market_kind=dex&chain=ethereum&address=0xC02aaA39b223FE8D0A0E5C4F27eAD9083C756Cc2

2. Ask an agent for token price or market context

• Best surface: Use MCP
• Tools: market.read_price, market.resolve_market
• Related pages: Get price snapshot, Get market profile
• Why: shortest path from prompt or tool call to structured output.

3. Build a live price board

• Best surface: Market WebSocket price streams
• Start page: Use Market WebSocket
• Why: live market feed without polling.

{
  "action": "subscribe",
  "targets": [
    {
      "market_kind": "dex",
      "target_id": "0xC02aaA39b223FE8D0A0E5C4F27eAD9083C756Cc2",
      "chain": "ethereum",
      "event_family": "price"
    }
  ]
}

4. Render short-range OHLCV charts

• Best surfaces: Get OHLCV window for request-response reads, OHLCV streams for live updates
• Why: recent candles for charts, watchlists, or summaries.

5. Enrich a token with identity and metadata

• Best surfaces: Get asset profile
• Why: name, symbol, decimals, and asset identity before showing market data.

6. Check market context before actioning a market

• Best surfaces: Get market profile
• Why: market context before alerts, rankings, or execution decisions.

7. Build price alerts or threshold watchers

• Best surfaces: Price streams for continuous checks, Get price snapshot for scheduled pulls
• Why: continuous or scheduled threshold checks.

8. Watch EVM heads, logs, or pending transactions

• Best surface: EVM RPC WebSocket API
• Specific pages: newHeads, logs, newPendingTransactions
• Why: native chain subscriptions instead of normalized market events.

9. Send direct EVM JSON-RPC methods

• Best surfaces: Use RPC, EVM HTTP API, EVM RPC HTTP API
• Why: Ethereum-style method semantics such as eth_chainId, eth_blockNumber, eth_call, or eth_getLogs.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_blockNumber",
  "params": []
}

10. Verify the current public endpoint baseline

• Best surface: Public Status API
• Why: one backend-owned view of published endpoints.

11. Start from a typed client in a TypeScript app

• Best surface: Typescript-SDK
• Why: shared auth wiring, endpoint setup, and typed helpers.

12. Decide whether to use Market API or EVM RPC

• Use Market API when the job is price, OHLCV, asset profile, or market profile.
• Use EVM RPC when the job is native chain access, direct JSON-RPC methods, or chain subscription topics.
• Use Market WebSocket when the job is product-level realtime market delivery.

13. Diagnose failed requests

• Best pages: Parameter Contracts, Public Status API, Use HTTP, Use RPC
• Why: confirm parameter rules, endpoint availability, and failure identifiers.

14. Review Solana compatibility coverage

• Best surface: Solana (Beta)
• Why: review the current beta method and subscription coverage.