Skarb API

Who can use it

Sending your own data — on every plan. Reading your portfolio and scores and MCP for AI agents — from Pro: on Pro the agent reads, on Ultra it acts as well.

Quick start

Make a token in the settings, the “API” tab, and confirm it with the code the bot sends you. It is shown once — save it right away.

Check the token works:

curl https://api.skarb.dev/v1/me \
  -H "Authorization: Bearer skb_…"

Make a source of your own — a connection with its account in the portfolio you pick:

curl -X POST https://api.skarb.dev/v1/connections \
  -H "Authorization: Bearer skb_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "My broker", "portfolio": "main", "currency": "USD"}'

Send trades — up to 1000 rows at a time. A share by its ISIN, a fund by its ticker and the venue’s MIC, a coin by its symbol:

curl -X POST https://api.skarb.dev/v1/connections/<id>/trades \
  -H "Authorization: Bearer skb_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-2026-10-08" \
  -d '{
    "trades": [
      {
        "externalId": "t-1001",
        "instrument": { "assetClass": "stock", "isin": "US0378331005" },
        "side": "buy",
        "quantity": "10",
        "price": "187.50",
        "currency": "USD",
        "fee": "1.00",
        "executedAt": "2026-09-30T14:32:10+02:00"
      },
      {
        "externalId": "t-1002",
        "instrument": { "assetClass": "etf", "ticker": "VWCE", "mic": "XETR" },
        "side": "buy",
        "quantity": "5",
        "price": "121.30",
        "currency": "EUR",
        "executedAt": "2026-10-01T10:05:00+02:00"
      },
      {
        "externalId": "t-1003",
        "instrument": { "assetClass": "crypto", "symbol": "BTC" },
        "side": "buy",
        "quantity": "0.05",
        "price": "62000",
        "currency": "USDT",
        "executedAt": "2026-10-02T08:00:00Z"
      }
    ]
  }'

Open your portfolio: the holdings are there, the cost by FIFO.

The same in Python — reading the portfolio (from Pro):

import requests

API = "https://api.skarb.dev/v1"
HEADERS = {"Authorization": "Bearer skb_…"}

portfolio = requests.get(f"{API}/portfolio", headers=HEADERS, timeout=30)
portfolio.raise_for_status()
for position in portfolio.json()["positions"]:
    print(position["instrument"]["ticker"], position["marketValue"], position["weight"])

Authorization and safety

The token goes in the Authorization: Bearer skb_… header only. In the address, a cookie or another header it is refused.

A token is shown once; only its hash is kept. Revoking it in the settings works at once.

A token has an expiry, scopes (sending, reading) and, on Ultra, a list of addresses. It can be tied to one connection or one portfolio — then it sees no other.

A token leaked — revoke it and make a new one. Twenty wrong tokens from one address in ten minutes shut the address out for an hour.

Limits

The day’s limits start over at midnight in Kyiv.

Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and the day’s rest X-Quota-Daily-Limit and X-Quota-Daily-Remaining. On a 429, wait the seconds Retry-After says.

A batch sent again within a day with the same Idempotency-Key gets the same answer and writes nothing twice. Put one on every batch.

Sending data

A connection is your own source of data with its account in the portfolio you pick. Trades and movements of money come in batches of up to 1000 rows.

A row with the same externalId is the same row: sent again it makes no double, changed it is updated.

An instrument: a share or a fund by its ISIN or its ticker with the venue’s MIC, a coin by its symbol. Skarb looks for it at once; not found, the row waits as pending, and you can match it by hand on the accounts page.

Coin trades in USDT and USDC are kept in dollars one to one. Movements of money are signed: a deposit above zero, a withdrawal below.

Emptying a connection (reset) and deleting it (DELETE) need the X-Confirm header — neither can be undone.

Reading

From Pro a token with the read scope gives your own data and Skarb’s derivatives of it. The portfolio is the main and the secondary together, as on the site, unless slot names one.

Scores — up to 20 tickers at a time. The score of what you hold or watch is free; the rest are taken off the same daily count of asset scores as on the site and in the bot.

The answer of GET /v1/portfolio:

{
  "asOf": "2026-10-08T09:30:00.000Z",
  "slot": "all",
  "baseCurrency": "USD",
  "totals": {
    "marketValue": "2000",
    "cost": "1500",
    "unrealizedPnl": "500",
    "unrealizedPnlPct": "33.33",
    "realizedPnl": "0",
    "cash": []
  },
  "positions": [
    {
      "instrument": {
        "id": "…",
        "ticker": "AAPL",
        "name": "Apple Inc.",
        "assetClass": "stock",
        "holdingClass": "stock",
        "currency": "USD",
        "sector": "Information Technology"
      },
      "quantity": "10",
      "avgCost": "150",
      "lastPrice": "200",
      "marketValue": "2000",
      "weight": "100",
      "unrealizedPnl": "500",
      "unrealizedPnlPct": "33.33",
      "score": { "quality": "72.4", "signal": 1, "confidence": "high", "asOf": "2026-10-07" }
    }
  ]
}

What the API does not and will not give: quotes, candles, price history, on-chain series, derivatives, insider trades, funds’ holdings, filings and calendars. The rights to those belong to their sources. A price is there only as the value of a holding you have.

MCP

The MCP server gives an AI agent — Claude Code, Cursor and others — your data in Skarb, and on Ultra its actions too. You need a token with the MCP scope — Pro has it. A call of a tool is one request of the API out of the day’s limit; the handshake and the list of tools are free. What to ask the agent and what it cannot do — on the page Skarb in an AI agent.

Claude Code, in one command:

claude mcp add --transport http skarb https://api.skarb.dev/mcp --header "Authorization: Bearer skb_…"

Cursor and other clients — JSON with the address and the header:

{
  "mcpServers": {
    "skarb": {
      "url": "https://api.skarb.dev/mcp",
      "headers": { "Authorization": "Bearer skb_…" }
    }
  }
}

claude.ai and ChatGPT connectors connect by signing in to Skarb, with no token: the server is https://api.skarb.dev/mcp, then the browser opens the sign-in and “Allow”. Claude Code the same way, with no header:

claude mcp add --transport http --scope user skarb https://api.skarb.dev/mcp

For authors of clients

Skarb is its own authorization server: OAuth 2.1, the code flow with PKCE S256. Metadata — /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on api.skarb.dev. A client registers itself (RFC 7591, POST /oauth/register), with no secret. A redirect URI is taken only over https to a known host — Claude, ChatGPT, Cursor and their subdomains — or to this computer: http://localhost, 127.0.0.1 and [::1] on any port. Need another host — write to us. An access token lives an hour, a refresh token 30 days with rotation: each exchange gives a new one, and the old one is taken again for 30 seconds only.

ChatGPT Pro gives an agent the reading tools alone: evaluate_trade and the other actions work on ChatGPT Business, Enterprise and Edu.

Actions spend the same daily limits as the site and the bot: trade checks, rebalance what-ifs and diary entries, while alerts and the watchlist stop at the plan’s size. There are no tools with quotes, candles, on-chain data or derivatives — for the same reason as in the API.

Errors

An error is JSON with one field, error: a code for a program, a message for a person, and on a 422 the fields that did not pass.

{
  "error": {
    "code": "validation_failed",
    "message": "A decimal string, such as \"12.5\"",
    "details": [{ "path": "trades[0].price", "issue": "A decimal string, such as \"12.5\"" }]
  }
}

OpenAPI

The whole contract is openapi.json (OpenAPI 3.1). It is built from the same schemas the API checks requests with, so it does not drift from the code.