Overview
The API is a small set of read-only JSON endpoints over HTTPS. Tickers use Yahoo format: NVDA, BRK-B, 0700.HK, 600519.SS, 300750.SZ.
- Base URL
- https://pickskill.ai/api/v1
- Response format
- A successful call returns HTTP 200 with data and credits. Every data object includes a disclaimer: PickSkill data is for research and education, not investment advice.
Authentication
Create a key on your API dashboard and send it in the Authorization header as a Bearer token (or in an x-api-key header). Keys start with psk_. Keep them secret; you can revoke a key at any time.
Authorization: Bearer psk_…
# or
x-api-key: psk_…Credits
Each successful call spends credits from your prepaid balance; failed calls are refunded. Every account starts with 100 free credits, and the API and the MCP server share one balance.
| GET/signals | 1 |
| POST/screen | 3 |
| GET/earnings | 2 |
| GET/portfolios | 1 |
| GET/credits | free |
Each response reports the credits charged and remaining in the body and in the X-Credits-Charged and X-Credits-Remaining headers.
Errors
Errors return a JSON body with an error code, a message and a link to these docs.
{
"error": {
"code": "insufficient_credits",
"message": "Not enough API credits: this call needs 3, your balance is 2. …",
"docs": "https://pickskill.ai/data-api/docs"
},
"credits": { "remaining": 2 }
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_input | The input is invalid — for example a missing ticker or a malformed screen condition. Refunded. |
| 401 | unauthorized | The API key is missing, invalid or revoked. |
| 402 | insufficient_credits | Not enough credits for this call. The body includes your balance. |
| 404 | not_found / unknown_tool | Unknown endpoint. |
| 405 | method_not_allowed | Wrong HTTP method for this endpoint. |
| 500 | internal_error | Something went wrong on our side. |
| 502 | upstream_error | A data provider failed. Refunded; try again shortly. |
Endpoints
GET/api/v1/signalsCost: 1Get stock signals
Latest close, 1-day and 5-day change, and eight technical signals — each bullish, bearish or neutral with a 5-day trail and the latest indicator values.
Parameters
tickersquery · required | Comma-separated tickers, up to 10. US, Hong Kong (.HK) or China A-shares (.SS, .SZ). |
Example request
curl "https://pickskill.ai/api/v1/signals?tickers=NVDA,0700.HK" \
-H "Authorization: Bearer $PICKSKILL_API_KEY"Example response
{
"data": {
"disclaimer": "For research and education only. Not investment advice.",
"legend": "signals[dim].now = latest reading; last5 = …",
"stocks": [
{
"ticker": "NVDA",
"asOf": "2026-11-17",
"close": 156.14,
"changePct": -1.2,
"fiveDayChangePct": 3.4,
"signals": {
"macd": { "now": "bullish", "last5": "NBBBB", "values": { "dif": 2.1, "dea": 1.7 } },
"rsi": { "now": "neutral", "last5": "NNNNN", "values": { "rsi": 58.4 } },
"…": "kdj, ma, boll, adx, volume, flow"
},
"bullishCount": 6,
"bearishCount": 1,
"page": "https://pickskill.ai/stocks/NVDA"
}
]
},
"credits": { "charged": 1, "remaining": 99 }
}POST/api/v1/screenCost: 3Screen stocks
Find stocks in the S&P 500, Nasdaq-100, Hang Seng and CSI 300 (plus PickSkill stock pages) that match every condition, with the evidence for each. Send a JSON body.
Parameters
conditionsbody · required | One to eight conditions, all of which must match. See Screen conditions. |
indicesbody · optional | Limit to index members: sp500, ndx, hsi, csi300. |
marketsbody · optional | Limit to markets: us, hk, cn. |
sort_bybody · optional | bullish_count (default), change_pct, five_day_change_pct or rsi. |
limitbody · optional | Matches to return, 1–30. Default 15. |
Example request
curl -X POST "https://pickskill.ai/api/v1/screen" \
-H "Authorization: Bearer $PICKSKILL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"indices": ["sp500"],
"conditions": [
{ "type": "event", "event": "macd_golden_cross", "within_days": 3 },
{ "type": "value", "field": "rsi.rsi", "op": "<", "value": 50 }
],
"limit": 10
}'Example response
{
"data": {
"universe": "… [sp500]: 503 stocks screened.",
"matchedCount": 10,
"matches": [
{
"ticker": "CAT",
"name": "Caterpillar",
"market": "us",
"indices": ["sp500"],
"close": 512.3,
"bullishCount": 6,
"evidence": [
"MACD golden cross 1 day ago (DIF 4.12, DEA 3.80)",
"rsi.rsi = 47.6 (< 50)"
],
"page": "https://pickskill.ai/stocks/cat"
}
]
},
"credits": { "charged": 3, "remaining": 96 }
}GET/api/v1/earningsCost: 2Get earnings highlights
A company's latest earnings release — report date, actual vs. estimated EPS and surprise — plus key ratios for valuation, margins, returns, leverage and growth. Most complete for US-listed companies.
Parameters
tickerquery · required | One ticker. |
Example request
curl "https://pickskill.ai/api/v1/earnings?ticker=NVDA" \
-H "Authorization: Bearer $PICKSKILL_API_KEY"Example response
{
"data": {
"ticker": "NVDA",
"latestEarnings": {
"report_date": "2026-08-26",
"report_time": "After Hours",
"eps_actual": 2.22,
"eps_estimate": 2.09,
"eps_surprise_percent": 6.22
},
"keyRatios": {
"pe_ratio": 20.2,
"forward_pe": 10.1,
"gross_margin": 0.75,
"return_on_equity": 1.17,
"quarterly_revenue_growth": 1.06,
"debt_to_equity": 0.17,
"…": "…"
},
"sources": ["…"]
},
"credits": { "charged": 2, "remaining": 94 }
}GET/api/v1/portfoliosCost: 1Read your portfolios
Your saved PickSkill portfolios with holdings, weights and, for each holding, the latest change and signal counts.
Parameters
portfolioquery · optional | A portfolio name or id. Omit to read all portfolios. |
include_signalsquery · optional | Set to false to skip per-holding signals. Default true. |
Example request
curl "https://pickskill.ai/api/v1/portfolios?include_signals=true" \
-H "Authorization: Bearer $PICKSKILL_API_KEY"Example response
{
"data": {
"portfolios": [
{
"id": "…",
"name": "Core",
"holdings": [
{
"ticker": "AAPL",
"name": "Apple",
"weightPct": 25,
"close": 228.4,
"changePct": 0.8,
"signals": { "macd": { "now": "bullish", "last5": "NBBBB", "values": { … } }, "…": "…" },
"bullishCount": 5,
"bearishCount": 1
}
]
}
]
},
"credits": { "charged": 1, "remaining": 93 }
}GET/api/v1/creditsCost: freeCheck your credits
Your credit balance, the cost of each endpoint and the available credit packs. Free to call.
Example request
curl "https://pickskill.ai/api/v1/credits" \
-H "Authorization: Bearer $PICKSKILL_API_KEY"Example response
{
"data": {
"balance": 93,
"costPerCall": { "get_stock_signals": 1, "get_my_portfolio": 1, "get_earnings_highlights": 2, "screen_stocks": 3 },
"packs": [ { "credits": 1000, "priceUsd": 10 }, { "credits": 5000, "priceUsd": 45 }, { "credits": 20000, "priceUsd": 160 } ],
"buyUrl": "https://pickskill.ai/account/api"
}
}Screen conditions
Conditions are objects with a type. Combine up to eight; a stock matches only when all of them hold.
type: "signal"
A dimension reads bullish, bearish or neutral, optionally for the last N days (1–5). RSI and KDJ "bullish" means oversold.
{ "type": "signal", "dimension": "ma", "is": "bullish", "days": 3 }type: "value"
An indicator value compared with a number: <, <=, > or >=.
{ "type": "value", "field": "rsi.rsi", "op": "<", "value": 30 }type: "event"
A MACD or MA5/MA20 golden or death cross, or a dimension turning bullish or bearish, within the last N days (1–5).
{ "type": "event", "event": "macd_golden_cross", "within_days": 3 }- Dimensions
macdmarsikdjbolladxvolumeflow- Common fields
rsi.rsikdj.kkdj.dkdj.jmacd.difmacd.histadx.adxboll.bandwidthvolume.volRatioprice.changePctprice.fiveDayChangePct- Events
macd_golden_crossmacd_death_crossma5_ma20_golden_crossma5_ma20_death_crossturned_bullishturned_bearish
Using MCP instead
Prefer to let an AI agent call the tools? The MCP server exposes the same four tools to Claude, Cursor, VS Code and other MCP clients, with the same key and the same credits.
Set up the MCP serverPickSkill data describes past prices and is for research and education only. It is not investment advice.