API reference

PickSkill API documentation

Everything you need to call the PickSkill REST API: base URL, authentication, credits, errors and each endpoint with examples.

Create an API keyhttps://pickskill.ai/api/v1

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_…
Create an API key

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/signals1
POST/screen3
GET/earnings2
GET/portfolios1
GET/creditsfree

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 }
}
StatusCodeMeaning
400invalid_inputThe input is invalid — for example a missing ticker or a malformed screen condition. Refunded.
401unauthorizedThe API key is missing, invalid or revoked.
402insufficient_creditsNot enough credits for this call. The body includes your balance.
404not_found / unknown_toolUnknown endpoint.
405method_not_allowedWrong HTTP method for this endpoint.
500internal_errorSomething went wrong on our side.
502upstream_errorA data provider failed. Refunded; try again shortly.

Endpoints

GET/api/v1/signalsCost: 1

Get 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 · requiredComma-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: 3

Screen 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 · requiredOne to eight conditions, all of which must match. See Screen conditions.
indicesbody · optionalLimit to index members: sp500, ndx, hsi, csi300.
marketsbody · optionalLimit to markets: us, hk, cn.
sort_bybody · optionalbullish_count (default), change_pct, five_day_change_pct or rsi.
limitbody · optionalMatches 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: 2

Get 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 · requiredOne 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: 1

Read your portfolios

Your saved PickSkill portfolios with holdings, weights and, for each holding, the latest change and signal counts.

Parameters

portfolioquery · optionalA portfolio name or id. Omit to read all portfolios.
include_signalsquery · optionalSet 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: free

Check 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 server

PickSkill data describes past prices and is for research and education only. It is not investment advice.