Use the Stock Trends API with x402

This page explains how AI agents and developers can call premium Stock Trends API endpoints using x402 per-request payment — no subscription required.

x402 is live in production and validated on GET /v1/agent/screener/top and GET /v1/stim/latest. The recommended first endpoint for new agent integrations is GET /v1/agent/screener/top.

What is x402 agent pay?

x402 is an HTTP-native payment protocol designed for machine-to-machine payment flows. When an agent calls a premium endpoint without a subscription API key, the Stock Trends API returns HTTP 402 Payment Required with the payment requirements for that request.

The agent pays on-chain on the Base network using USDC, then retries the original request with payment proof headers. The API validates the proof and returns the full premium response.

No API key or subscription is required. You pay only for the calls you make.

Pricing clarity: STC and USD cost

Stock Trends Credits (STC) are the API's pricing unit. For current billing and payment presentation, 1 STC = $1.00 USD. This means a request priced at 0.50 STC costs $0.50 USD, a request priced at 0.75 STC costs $0.75 USD, and a request priced at 1.25 STC costs $1.25 USD.

x402 and MPP requests may be settled through machine-payment rails, including USDC on Base where supported, but the user-facing economic cost is still shown from the STC-denominated endpoint price. The live pricing catalog and response headers remain authoritative before execution.

Recommended first endpoint

Start with the agent screener. It is the primary x402-validated endpoint and returns top-ranked instruments filtered by trend, exchange, and RSI.

GET https://api.stocktrends.com/v1/agent/screener/top

Pricing: 0.50 STC ($0.50 USD) per call. Optional query parameters: exchange, trend, limit, sort, min_rsi.

Discover live endpoint pricing before executing requests:

GET https://api.stocktrends.com/v1/pricing/catalog

The live pricing catalog and API response headers are authoritative for endpoint costs.

First flow: step by step

Step 1 — Start with the public API reference

The interactive docs and OpenAPI schema are the confirmed public entry points. Use these to explore endpoints, parameters, and response shapes.

https://api.stocktrends.com/v1/docs
https://api.stocktrends.com/v1/openapi.json

Step 2 — Discover pricing

Check the live pricing catalog to understand endpoint costs before executing requests.

GET https://api.stocktrends.com/v1/pricing/catalog

Step 3 — Call the premium endpoint

Call GET /v1/agent/screener/top without a subscription key to initiate the x402 flow.

GET https://api.stocktrends.com/v1/agent/screener/top

Step 4 — Handle HTTP 402 Payment Required

The API returns HTTP 402 with payment requirements for this request. Review the response for the required payment amount and on-chain payment details. Refer to the live API docs for the current 402 response structure.

Step 5 — Pay on-chain

Submit the required USDC payment on the Base network. Retain your transaction hash — you will need it for the payment proof headers in the next step.

Step 6 — Retry with payment proof headers

Retry the original request with the following payment proof headers:

GET https://api.stocktrends.com/v1/agent/screener/top
X-StockTrends-Payment-Method: x402
X-StockTrends-Payment-Network: base
X-StockTrends-Payment-Token: USDC
X-StockTrends-Payment-Reference: 0x...your_tx_hash

Step 7 — Receive the premium response

The API validates the payment proof and returns the full screener response with top-ranked instruments, trend classifications, and RSI data.

Concrete examples

Subscription path — API key

curl "https://api.stocktrends.com/v1/agent/screener/top" \
  -H "X-API-Key: YOUR_API_KEY"

# Optional filters
# ?exchange=N&limit=10&sort=rsi&trend=^+,^-

x402 path — Step 1: initial call (no key)

curl -i "https://api.stocktrends.com/v1/agent/screener/top"

# Returns HTTP 402 with payment requirements.
# Review the response for the required amount and payment details.

x402 path — Step 2: retry with payment proof

curl "https://api.stocktrends.com/v1/agent/screener/top" \
  -H "X-StockTrends-Payment-Method: x402" \
  -H "X-StockTrends-Payment-Network: base" \
  -H "X-StockTrends-Payment-Token: USDC" \
  -H "X-StockTrends-Payment-Reference: 0x...your_tx_hash"

Secondary endpoint: /v1/stim/latest (also x402-validated)

curl "https://api.stocktrends.com/v1/stim/latest?symbol_exchange=IBM-N" \
  -H "X-StockTrends-Payment-Method: x402" \
  -H "X-StockTrends-Payment-Network: base" \
  -H "X-StockTrends-Payment-Token: USDC" \
  -H "X-StockTrends-Payment-Reference: 0x...your_tx_hash"

Payment headers reference

Header	Value	Description
X-StockTrends-Payment-Method	x402	Payment rail identifier
X-StockTrends-Payment-Network	base	Blockchain network for on-chain payment
X-StockTrends-Payment-Token	USDC	Payment token
X-StockTrends-Payment-Reference	0x...tx_hash	On-chain transaction hash as payment proof

Optional: agent identity headers

X-StockTrends-Agent-Id: your-agent-id
X-StockTrends-Agent-Type: autonomous
X-StockTrends-Agent-Vendor: your-vendor
X-StockTrends-Request-Purpose: screening

Agent identity headers are optional but improve usage tracking and ledger visibility via GET /v1/agents/{agent_id}/usage and /ledger.

What's next

• Machine Payment Protocol (MPP) — funded session-based agent pay for repeated premium workflows. See the MPP quickstart.
• Usage and ledger tracking — Include agent identity headers to track per-agent usage via GET /v1/agents/{agent_id}/usage and GET /v1/agents/{agent_id}/ledger.
• Full endpoint set — x402 payment support is available across premium endpoints. Inspect the pricing catalog for current coverage and costs.