Skip to content

Get started

Quickstart

Send a first portfolio and read the answer.

  1. Get an API key.

    Keys are issued by us; contact us for one. Keep the key on your servers: never put it into a browser, a mobile app or a URL. The examples below read it from the environment variable SILK_API_KEY.

  2. Describe the portfolio.

    Save this as portfolio.json:

    portfolio.json
    {
    "holdings": [
    {
    "identifier": "AAPL.XNAS",
    "identifier_type": "symbol",
    "weight": 0.40
    },
    {
    "identifier": "SAP.XETR",
    "identifier_type": "symbol",
    "weight": 0.35
    },
    {
    "identifier": "IWDA.XAMS",
    "identifier_type": "symbol",
    "weight": 0.14
    },
    {
    "identifier": "XAU.COMMODITY",
    "identifier_type": "symbol",
    "weight": 0.03
    },
    {
    "identifier": "NEWCO.XNAS",
    "identifier_type": "symbol",
    "weight": 0.08
    }
    ],
    "currency": "EUR"
    }
    Field What it holds
    identifier The instrument as TICKER.MIC: the ticker, a dot, and the venue’s Market Identifier Code. AAPL.XNAS is Apple on Nasdaq; the same ETF is IWDA.XAMS in Amsterdam and EUNL.XETR on Xetra. Crypto uses .CRYPTO (ETH.CRYPTO), precious-metal spot .COMMODITY (XAU.COMMODITY for gold).
    identifier_type symbol.
    weight The holding’s share of the portfolio as a fraction: 0.40 is 40 %. Each weight is above 0 and at most 1; together they sum to 1 (±0.001).
    currency The reporting currency. EUR today.

    A request holds 1 to 100 holdings. Weights only: no amounts, no account or customer data.

  3. Send it.

    curl https://api.aegoralabs.de/v1/analysis \
    -H "Authorization: Bearer $SILK_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @portfolio.json \
    --max-time 30
  4. Read the answer.

    The response, shortened here to the fields you will use first:

    200 OK
    {
    "methodology_version": "0.3",
    "result_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "resilience_score": 44,
    "rating": "average",
    "subscores": {
    "scenario_survival": { "score": 48, "rating": "average" },
    "drawdown_resistance": { "score": 34, "rating": "weak" },
    "concentration": { "score": 45, "rating": "average" },
    "correlation_fragility": { "score": 41, "rating": "average" },
    "volatility": { "score": 72, "rating": "good" }
    },
    "scenario_losses": { "covid_2020": -0.24, "rate_shock_2022": -0.17 },
    "coverage": { "scored_weight": 0.92, "excluded_weight": 0.08 },
    "resolved_holdings": [
    { "identifier": "AAPL.XNAS", "identifier_type": "symbol", "label": "Apple Inc.", "exclusion_reason": null },
    { "identifier": "NEWCO.XNAS", "identifier_type": "symbol", "label": "NewCo Holdings Inc.", "exclusion_reason": "insufficient_history" }
    ]
    }
    Field How to read it
    resilience_score 0 to 100, higher is better.
    rating The score in words: weak below 40, average below 70, good from 70. Every subscore has its own.
    subscores The five parts the score is built from.
    scenario_losses The portfolio’s return in two historical crash windows, as a fraction: -0.24 is −24 %.
    coverage How much of the submitted weight was scored and how much was left out.
    resolved_holdings Every holding you sent, in your order. exclusion_reason is null when the holding was scored, otherwise it says why it was left out.
    result_id Names this request. Quote it if you contact us; the result itself cannot be fetched again.

    The full response, including the metrics behind each subscore, is in the API reference.

A holding that cannot be scored does not fail the request. It is left out, and the remaining weights are scaled up to sum to 1 before scoring: a 60/40 portfolio with the 40 left out is scored as 100 % of the first holding. coverage shows how much was left out, and exclusion_reason says why:

exclusion_reason Meaning
null The holding was scored.
unresolved_symbol Not a valid TICKER.MIC, a venue that is not supported, or an instrument the market data does not know.
unsupported_asset_type A kind of instrument that is not scored, such as a derivative.
insufficient_history Not enough price history: it has to reach back to 19 February 2020, the start of the covid_2020 window.
holdings_unavailable A fund whose holdings are not available. The fund is left out as a whole.

If so much is left out that the result would not mean anything, the request fails with INSUFFICIENT_COVERAGE instead of returning a misleading score.

Every error has an HTTP status and a body with a stable code; branch on code. A 4xx status means the request has to change, a 5xx status means the problem is on our side. The error pages say for each code what happened and what to do.