> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcus.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get market metadata > Returns curated reference data (company profile, branding, headline financials, TradingView chart identifiers, …) for one or all markets served by the api-meta service. Returns curated reference data (company profile, branding, headline financials, TradingView chart identifiers, …) for one or all markets served by the api-meta service. The unfiltered set includes the api-gateway market universe plus curated RH spot/equity-like markets. Public — no `X-API-Key` and no signature required. Without `?market=` the full set is returned; with `?market=` (e.g. `BTC-USD`) the response is a single-row envelope. Data is refreshed in the background from the upstream reference feed roughly every 30 minutes; clients should cache downstream accordingly and use `ingestedAt` to bound staleness. Fields with no upstream source today (CEO, P/E ratio, dividend yield, quarterly earnings, country) serialize as `null` / `[]`. See `MarketMetadata` for the full per-row contract. ## OpenAPI ````yaml /api-reference/openapi.yml get /v1/api-meta/markets openapi: 3.1.0 info: title: Arcus API version: 1.0.0 description: > REST API for the Arcus exchange. Provides endpoints for order management, market data, and account onboarding. ## Coming soon (not implemented yet) The following features are declared in this spec (or implied by it) but are **not yet live** on the gateway or matching engine. Schemas and endpoints may be present so clients can wire against the final shape, but today the gateway returns `501 Not Implemented` or the feature is simply absent. Do not depend on these in production until they are announced as live. - **Modify order** (`POST /modifyOrder`) — reduce-only modifications will preserve queue priority; any change that moves the price level or increases size will be handled as an atomic cancel + replace (queue priority is lost). Currently returns `501 Not Implemented`. - **Batch modify order** (`POST /batchModifyOrders`) — same semantics as `modifyOrder`, applied atomically per item. Currently returns `501 Not Implemented`. - **Next predicted funding rate** — the predicted funding rate for the upcoming interval is not yet exposed on `GET /markets` or the markets WebSocket channel. Only the current realized rate is available today. - **Funding rate calculations** — the authoritative calculation methodology (premium sampling window, interest-rate component, clamping, payment schedule) is still being finalized and is not documented here yet. - **Advanced order types** — trailing stop, stop-limit, OCO, and other conditional / bracket order variants beyond plain `LIMIT` and `MARKET` are not yet supported. ## Authentication Order management and credential-creating endpoints require **three** request headers: - `X-API-Key` — hex-encoded Ed25519 public key (64 chars). The public key *is* the API key. Obtain/register one via `POST /createApiKey`. - `X-Timestamp` — Unix time in **nanoseconds** as a decimal string (e.g. `"1713825891591000000"`). Millisecond or second epochs are rejected with `401 Unauthorized`. Must be within ±30,000 ms (`MaxTimestampDriftMs`, the drift window stays configured in milliseconds) of server wall-clock; otherwise the request is rejected with `401 Unauthorized`. - `X-Signature` — lowercase hex-encoded Ed25519 signature (128 chars). **Single-order endpoints** (`placeOrder`, `cancelOrder`, `modifyOrder`) use the **ordersign typed canonical payload** as the signing message — a compact, key-sorted JSON object with engine-native integer values. The payload is NOT the raw HTTP body; it is built from the parsed request fields: ``` placeOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,"m":N,"op":1,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1} cancelOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1} modifyOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"v":1} ``` `ct` in the payload must equal `X-Timestamp`. Integer values `p`, `q` etc. are engine-native ticks/quantums, not human-readable decimals. Keys in brackets are conditional (omitted when empty). `op` is the operation enum: `1`=place, `2`=cancel, `3`=modify, `4`=placeUntriggered (TPSL). See the `ordersign` package for full field definitions and reference signing code. **Batch endpoints do not use this header** — see below. - **Batch endpoints are signed per order — no `X-Signature`.** `POST /batchPlaceOrders` and `POST /batchCancelOrders` require `X-API-Key` + `X-Timestamp` only; the gateway does **not** verify an envelope `X-Signature` for these routes. Instead, each element of the `orders` / `cancels` array embeds its own `"signature"` field — a 128-hex Ed25519 signature over the **ordersign typed canonical payload** for that operation: - Plain `orders` elements (no `tpsl_type`) use `op=1`. - TPSL / conditional `orders` elements (with `tpsl_type`) use `op=4` (`OpPlaceUntriggered`) — same field set as `op=1` but a different `op` value, preventing replay of a TPSL signature as a plain placeOrder. - `cancels` elements use `op=2`. The `ct` field inside every element's payload must equal the shared `X-Timestamp` header value. The whole batch consumes a single replay slot. Read-only endpoints (`GET /openOrders`, `GET /fills`, etc.) require only `X-API-Key`. In relaxed local development the gateway may run with signatures disabled; the OpenAPI `security` blocks list `signedRequest` (the three-header AND) or `{}` (empty) to reflect that. ## Account-scoped requests Public account info reads such as fills, positions, orders, open orders, and account snapshots require `address` as a **query parameter**. Signed order management requests also require `address`, and it must match the master Ethereum address returned for that API key from `POST /createApiKey`. WebSocket `placeOrder` / `cancel` / `batchPlaceOrders` / `batchCancelOrders` / `modifyOrder` use the same value in the JSON payload field `address`. ## Order execution is asynchronous `POST /placeOrder`, `POST /cancelOrder`, `POST /batchPlaceOrders`, and `POST /batchCancelOrders` are asynchronous. They return either: - **`202 Accepted`** — the common case. The signed request was validated by the gateway and forwarded to the matching engine; the body does **not** carry the order's terminal state. - **`200 OK`** — returned only when the gateway already has definitive state for the request by the time it responds (the body's `status` reflects that state, e.g. `OPEN` / `FILLED` / `CANCELED` / `REJECTED`). Clients should treat this as best-effort enrichment and not rely on it. In both cases the body echoes `orderId` / `clientId` so callers can correlate WebSocket events with the request. To observe the full order lifecycle (`OPEN`, `FILLED`, `CANCELED`, `REJECTED`, fills, rejection reasons, etc.) clients **must** subscribe to the `orders` WebSocket channel (and `userFills` for trade-level events). Treat both the `202` and `200` HTTP bodies as request acknowledgements; all definitive state lives on the WebSocket. `POST /modifyOrder` and `POST /batchModifyOrders` are **not implemented yet** — the schemas are declared so consumers can wire against the final shape, but the gateway returns `501 Not Implemented` today. When live, they will follow the same async contract. ## Order rejection reasons When the matching engine (go-core) rejects an order, the resulting `AccountUpdate` event (delivered over the WebSocket `account` channel with `type: REJECTED`) carries a `rejectionReason` enum. The same value may also appear on HTTP `OrderResponse` / `CancelOrderResponse` bodies that resolved to definitive state before returning (the `200` path described above). The complete set of reasons go-core can emit today is: | Value | Meaning | |------------------------------|-------------------------------------------------------------------------| | `POST_ONLY_WOULD_CROSS` | Post-only order was rejected because it would have crossed the book and taken liquidity. | | `SELF_TRADE` | Order would have matched against another resting order belonging to the same account; self-trade prevention rejected it. | | `UNDERCOLLATERALIZED` | Account has insufficient free collateral / margin to support the order. | | `COULD_NOT_FILL` | Generic "could not fill" outcome. Legacy reason — prefer the IOC/FOK-specific values below for time-in-force-driven cancels. | | `IOC_CANCELED` | An `IMMEDIATE_OR_CANCEL` order produced zero fills against the book and was canceled. | | `FOK_FAILED` | A `FILL_OR_KILL` order could not be filled in full at submission and was canceled in its entirety. | | `REDUCE_ONLY_WOULD_INCREASE` | A `reduceOnly` order was rejected because executing it would have opened or increased the account's position rather than reducing it. | | `TOO_MANY_CLIENT_IDS` | Account already has 10,000 live `clientId`s (the per-account maximum). Cancel an existing order or wait for one to reach a terminal state to free a slot. | | `DUPLICATE_CLIENT_ID` | The `clientId` already maps to a live order on this account. Cancel the prior order (or use atomic modify via `placeAndCancel`) before reusing the same `clientId`. | See the `RejectionReason` schema for the canonical enum. ## Rate limiting Rate-limited endpoints return `429 Too Many Requests` carrying two retry-after signals: - `Retry-After` HTTP header (integer seconds, RFC 7231 compliant). - `retryAfterMs` field in the JSON body — precise milliseconds. The body also carries a typed `reason` indicating which layer rejected (`ip`, `account_empty`, `account_partial`). See `RateLimitedError` for the schema and `TooManyRequests` for the behavioral contract. Partner market-makers may be added to the bypass allowlist via the `RATELIMIT_BYPASS_ADDRESSES` server-side configuration (per environment). Allowlisted addresses skip rate-limit charging entirely and never receive a 429 from this layer. servers: - url: https://api.testnet.arcus.xyz description: Testnet - url: https://api.arcus.xyz description: Mainnet security: [] tags: - name: Onboarding description: Account and API key management. - name: Public description: >- Unauthenticated endpoints — market data, health checks, and account-scoped info reads. - name: Exchange description: > Signed order management endpoints (all are HTTP `POST`). Every request must carry the full header triple `X-API-Key` + `X-Timestamp` + `X-Signature` where `X-Signature` is an Ed25519 signature over the operation-specific signing message: `placeOrder`, `cancelOrder`, and `modifyOrder` sign the ordersign typed canonical payload (the JSON object itself, no prefix), while `cancelAllOrders` and `setLeverage` use the legacy `X-Timestamp + ACTION + canonicalJSON(body)` message (ACTION = the final camelCase path segment; the HTTP method is not signed). `X-Timestamp` is a Unix nanosecond epoch (decimal string) and must be within ±30,000 ms of server wall-clock. See the top-level **Authentication** section for full details. These endpoints also require query parameter `address` matching the key's master Ethereum address. - name: Referral description: > Affiliate / referral program endpoints. Mutating endpoints (`POST`) require the full Ed25519 signature triple and the body `address` must match the API key's master Ethereum address. Read endpoints (`GET`) are public and scoped by `?address=`. - name: Meta description: > Product / UX-level APIs served by the `api-meta` service. These live behind the same host as the rest of the API but are routed (via the ALB path rule on `/v1/api-meta/*`) to a separate deployment with its own ScyllaDB keyspace and its own deployment lifecycle. They share the same `X-API-Key` + Ed25519 signature scheme as Exchange endpoints; the signed `REQUEST_PATH` includes the `/v1/api-meta/...` prefix verbatim. - name: UserPreferences description: > Per-master-wallet preference store (favorited markets, dashboard layouts, theme, language, …). Reads are public and scoped by `?address=`; writes (PATCH / DELETE) require an Ed25519 signature and are bound to the address registered to `X-API-Key`. See `UserPreferenceKey` for the known keys and `UserPreferenceValue` for the type system. - name: MarketMetadata description: > Curated reference data for markets (company profile, branding, headline financials, …) refreshed from the upstream ticker feed. Reads are public; freshness is bounded by the per-row `ingestedAt` returned in the response envelope. - name: Notifications description: > Per-master-wallet inbox of "unseen events" surfaced from the matching engine: terminal resting-order fills (maker side, fully filled), liquidations, and TP/SL triggers. Reads are public and scoped by `?address=`; the `:markSeen` write requires an Ed25519 signature and is bound to the address registered to `X-API-Key`. Notifications expire after 30 days. paths: /v1/api-meta/markets: get: tags: - MarketMetadata summary: Get market metadata description: >- Returns curated reference data (company profile, branding, headline financials, TradingView chart identifiers, …) for one or all markets served by the api-meta service. operationId: getMarketMetadata parameters: - name: market in: query required: false schema: type: string description: > Optional arcus market filter (e.g. `BTC-USD`). When set, the response contains exactly the matching row or `404`. responses: '200': description: Market metadata envelope (possibly empty `results`). content: application/json: schema: $ref: '#/components/schemas/MarketMetadataResponse' '404': description: Single-market lookup did not match any stored row. content: application/json: schema: $ref: '#/components/schemas/error' '503': description: Backing store unavailable. Caller should retry with backoff. content: application/json: schema: $ref: '#/components/schemas/error' x-codeSamples: - lang: Shell label: curl source: > curl https://api.testnet.arcus.xyz/v1/api-meta/markets curl "https://api.testnet.arcus.xyz/v1/api-meta/markets?market=BTC-USD" - lang: Python label: requests source: | import requests r = requests.get( "https://api.testnet.arcus.xyz/v1/api-meta/markets", params={"market": "BTC-USD"}, ) print(r.json()) - lang: TypeScript label: fetch source: > const url = new URL("https://api.testnet.arcus.xyz/v1/api-meta/markets"); url.searchParams.set("market", "BTC-USD"); const res = await fetch(url); console.log(await res.json()); components: schemas: MarketMetadataResponse: type: object required: - results - count - ingestedAt description: > Envelope returned by `GET /v1/api-meta/markets`. Both the unfiltered list call and the single-market lookup (`?market=`) share this shape; a single-market hit has `count == 1`. properties: results: type: array items: $ref: '#/components/schemas/MarketMetadata' count: type: integer format: int32 minimum: 0 description: Number of entries in `results`. ingestedAt: type: integer format: int64 minimum: 0 description: > Newest `ingested_at_ms` (Unix milliseconds) across the returned rows. `0` when `results` is empty. Use this to bound client-side cache freshness. error: type: object required: - error properties: error: type: string description: Human-readable error message. examples: - Invalid request body code: type: string description: > Machine-readable error code for generic (non-order) rejections. Present on geo-restriction blocks; clients should key product-availability UI off this rather than the human `error` string. | Value | Meaning | |------------------|---------| | `GEO_RESTRICTED` | The action is not available from the caller's country/region for this product (perps and/or spot). Reads remain available; only state-changing actions are blocked. | enum: - GEO_RESTRICTED errorSource: type: string description: > Scopes the failure to a specific operation. Present on structured order errors (place / cancel / modify flows); absent on generic HTTP errors. enum: - Order - Cancel errorType: type: string description: > Machine-readable reason for the API-layer rejection. Present alongside `errorSource` on structured order errors; absent on generic HTTP errors. | Value | Meaning | |-------------------|---------| | `Tick` | Price or size does not align to the market's tick size / step size. | | `InvalidRequest` | A request field failed validation (bad address, unknown market, invalid enum, etc.). TPSL-specific causes: `stopPrice` required when `tpslType` is set; `tpslType` must be `STOP_LOSS` or `TAKE_PROFIT`; `reduceOnly` must be `true` for TPSL orders; trigger price must not sit on the wrong side of the current oracle (would fire immediately); batch grouping/shape constraints violated (wrong order count, missing or duplicate `tpslType` legs). | | `OracleDeviation` | The order's price deviates from the current oracle price by more than the allowed threshold. Adjust the price closer to the oracle and resubmit. | | `ReduceOnly` | A reduce-only order was rejected because filling it would open or increase the account's position rather than reduce it. | | `Unavailable` | The requested operation (place / cancel) is temporarily disabled. | | `Unauthorized` | API key or trading-identity check failed. | | `Forbidden` | The authenticated key is not permitted to perform the requested operation. | | `NotImplemented` | The requested capability is not yet available on this path (e.g. TPSL over WebSocket). | | `Transmission` | The gateway accepted and validated the request but could not deliver it to the matching engine. Retry. | | `Internal` | Unexpected gateway-side failure unrelated to transmission. | enum: - Tick - InvalidRequest - OracleDeviation - ReduceOnly - Unavailable - Unauthorized - Forbidden - NotImplemented - Transmission - Internal rejectionReason: type: string description: > Machine-readable engine-level rejection code. Present on `OrderResponse` / `BatchOrderItemResponse` when `status` is `REJECTED` on the synchronous `200` path (i.e. the gateway already had a definitive engine reject before responding). Absent on `202` responses and on HTTP error bodies — in those cases rejection reasons are delivered asynchronously via the `orders` WebSocket channel. Mirror of the canonical `RejectionReason` schema in `openapi.yaml` — keep the two in lockstep (and the hardcoded list in `sdks/python/scripts/post_process_models.py`). | Value | Meaning | |------------------------------------|---------| | `POST_ONLY_WOULD_CROSS` | Post-only order would have crossed the book and taken liquidity. | | `SELF_TRADE` | Order would match against the account's own resting order; blocked by self-trade prevention. | | `UNDERCOLLATERALIZED` | Account has insufficient free collateral / margin to support the order. | | `COULD_NOT_FILL` | Generic "could not fill" (legacy; prefer `IOC_CANCELED` / `FOK_FAILED`). | | `IOC_CANCELED` | IOC order produced zero fills and was canceled. | | `FOK_FAILED` | FOK order could not be fully filled at submission. | | `REDUCE_ONLY_WOULD_INCREASE` | reduce-only order would have opened or increased the position. | | `TOO_MANY_CLIENT_IDS` | Account already has 10,000 live `clientId`s (the per-account maximum). Cancel or let existing orders reach a terminal state to free slots before placing new ones with distinct `clientId`s. | | `DUPLICATE_CLIENT_ID` | Account already has an open order with the same `clientId`. | | `POSITION_TPSL_ALREADY_EXISTS` | A position-level TPSL of the same trigger class (TP or SL) already exists for this account+market. At most one TP and one SL per market. | | `ENTRY_TPSL_CANNOT_BE_POSITION_TPSL` | A TPSL bound to an entry order (`parentOrderId` set) cannot also be a position-level TPSL; entry-linked TPSLs are sized partial legs. | | `OPEN_ORDER_CAP_EXCEEDED` | Account has reached its per-account open-order cap; cancel a resting order or let one reach a terminal state before placing another. | | `ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT` | Outside regular trading hours, a crossing order would have taken liquidity past the off-hours trading bound while the market is halted at that band. | | `ORDER_NOT_FOUND` | `cancelOrder` referenced an order not on the orderbook (already filled, canceled, never placed, or owned by another account). | | `ORDER_NOT_FOUND_FOR_MODIFY` | `modifyOrder` referenced an order not on the regular orderbook; TPSL and untriggered orders cannot be modified. | | `MODIFY_CHANGED_IMMUTABLE_FIELD` | `modifyOrder` attempted to change an immutable field (`side`, `timeInForce`, `reduceOnly`, or `orderType`). | | `MODIFY_ZERO_SIZE` | `modifyOrder` specified a new size of zero or less. | enum: - POST_ONLY_WOULD_CROSS - SELF_TRADE - UNDERCOLLATERALIZED - COULD_NOT_FILL - IOC_CANCELED - FOK_FAILED - REDUCE_ONLY_WOULD_INCREASE - TOO_MANY_CLIENT_IDS - DUPLICATE_CLIENT_ID - POSITION_TPSL_ALREADY_EXISTS - ENTRY_TPSL_CANNOT_BE_POSITION_TPSL - OPEN_ORDER_CAP_EXCEEDED - ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT - ORDER_NOT_FOUND - ORDER_NOT_FOUND_FOR_MODIFY - MODIFY_CHANGED_IMMUTABLE_FIELD - MODIFY_ZERO_SIZE MarketMetadata: type: object required: - ticker - tradingViewId - name - description - website - logo - sector - ceo - employees - headquarters - founded - financials - quarterlyEarnings - news description: > Curated, UX-shaped projection of the upstream ticker-overview record for one market. Nullable scalar fields are emitted as JSON `null` (never omitted) so clients can distinguish "unknown" from "zero". Curated RH spot markets include `tradingViewId` when the TradingView venue is known. Fields with no source for the active provider serialize as `null` / `[]`. `news` is always present as a non-null array (empty when there is no coverage). The `incomeStatements`, `balanceSheets`, and `cashFlowStatements` sections are FMP-only enrichment and are present only in responses produced by the FMP provider (omitted otherwise). properties: ticker: type: string description: > Upstream ticker symbol (e.g. `X:BTCUSD` for crypto, bare base symbol for equities / commodities / indices). Falls back to the arcus market name when the upstream ticker is missing. tradingViewId: type: string description: > TradingView chart identifier for curated spot/equity-like markets, e.g. `NASDAQ:NVDA`. `null` when no curated TradingView venue is known for the market. nullable: true name: type: string description: Display name of the issuing entity. description: type: string nullable: true website: type: string description: Homepage URL. nullable: true logo: type: string description: > Rewritten logo URL hosted on the arcus CDN. May be `null` when the upstream record has no branding. nullable: true sector: type: string description: SIC (or equivalent) sector description. nullable: true ceo: $ref: '#/components/schemas/MarketMetadataCEO' employees: type: integer format: int64 nullable: true headquarters: $ref: '#/components/schemas/MarketMetadataHeadquarters' founded: $ref: '#/components/schemas/MarketMetadataFounded' financials: $ref: '#/components/schemas/MarketMetadataFinancials' quarterlyEarnings: type: array items: $ref: '#/components/schemas/MarketMetadataQuarterlyEarning' news: type: array description: > Most-recent 20 news articles for the market, newest first. Sourced from FMP's /news/stock feed. Always a non-null array (`[]` when there is no coverage). items: $ref: '#/components/schemas/MarketMetadataNewsArticle' incomeStatements: type: array description: > Trailing 8 reported quarters of income statements, most-recent first. FMP provider only; omitted otherwise. items: $ref: '#/components/schemas/MarketMetadataIncomeStatement' balanceSheets: type: array description: > Trailing 8 reported quarters of balance sheets, most-recent first. FMP provider only; omitted otherwise. items: $ref: '#/components/schemas/MarketMetadataBalanceSheet' cashFlowStatements: type: array description: > Trailing 8 reported quarters of cash-flow statements, most-recent first. FMP provider only; omitted otherwise. items: $ref: '#/components/schemas/MarketMetadataCashFlowStatement' MarketMetadataCEO: type: object required: - name - title - since description: > Chief executive officer profile. No upstream source today, so every field is `null` — the object is always present so clients can rely on its shape. properties: name: type: string nullable: true title: type: string nullable: true since: type: string description: ISO date the current CEO took office, when known. nullable: true MarketMetadataHeadquarters: type: object required: - country - state - city - address description: > Postal address of the issuing entity, projected from the upstream `address` object. `country` is not provided upstream (the dataset is US-centric) and is always `null`. properties: country: type: string nullable: true state: type: string nullable: true city: type: string nullable: true address: type: string description: Combined street address (line 1 + line 2 joined by ", "). nullable: true MarketMetadataFounded: type: object required: - ipoDate - year description: > Listing / IPO date. `year` is the calendar year parsed from `ipoDate` when available; we do not track the company's actual incorporation year, so it reflects the IPO year. properties: ipoDate: type: string description: ISO date (`YYYY-MM-DD`) the security was first listed. nullable: true year: type: integer format: int64 nullable: true MarketMetadataFinancials: type: object required: - marketCap - peRatio - dividendYield - currency description: > Headline financial metrics. `marketCap` / `currency` are sourced by every provider; `peRatio` / `dividendYield` are filled by the Finnhub and FMP providers (`null` for Massive). The `revenue` (trailing-twelve-month), `evToSales`, `evToEBITDA`, and `priceToBook` fields are FMP-only enrichment: they are present (omitted otherwise) only in responses produced by the FMP provider. properties: marketCap: type: number format: double nullable: true peRatio: type: number format: double nullable: true dividendYield: type: number format: double nullable: true currency: type: string description: Reporting-currency code, e.g. `usd`. nullable: true revenue: type: number format: double description: > Trailing-twelve-month revenue (sum of the four most recent reported quarters). FMP provider only; omitted otherwise. nullable: true evToSales: type: number format: double description: >- Enterprise-value-to-sales (TTM). FMP provider only; omitted otherwise. nullable: true evToEBITDA: type: number format: double description: >- Enterprise-value-to-EBITDA (TTM). FMP provider only; omitted otherwise. nullable: true priceToBook: type: number format: double description: Price-to-book ratio (TTM). FMP provider only; omitted otherwise. nullable: true MarketMetadataQuarterlyEarning: type: object required: - period - fiscalQuarter - epsActual - epsEstimate - epsSurprise - epsSurprisePercent description: > One earnings-period row. No upstream source today; the array on `MarketMetadata` is always empty. Present in the shape for forward compatibility. properties: period: type: string description: ISO date of the period end (`YYYY-MM-DD`). nullable: true fiscalQuarter: type: string description: Fiscal-quarter label (e.g. `Q1 2025`). nullable: true epsActual: type: number format: double nullable: true epsEstimate: type: number format: double nullable: true epsSurprise: type: number format: double nullable: true epsSurprisePercent: type: number format: double nullable: true MarketMetadataNewsArticle: type: object required: - publishedDate - title - publisher - site - text - url - image description: > One recent news item for the market, sourced from FMP's /news/stock feed (capped at the most recent 20, newest first). Fields are plain strings; empty when the source omits them. properties: publishedDate: type: string description: ISO date-time string of publication. title: type: string publisher: type: string site: type: string text: type: string description: Article summary or excerpt. url: type: string description: Link to the full article. image: type: string description: Thumbnail image URL. MarketMetadataIncomeStatement: allOf: - $ref: '#/components/schemas/MarketMetadataStatementMeta' - type: object description: > One quarter of the FMP income statement. FMP provider only. Numeric line items are emitted as numbers (including `0`). properties: revenue: type: number format: double costOfRevenue: type: number format: double grossProfit: type: number format: double researchAndDevelopmentExpenses: type: number format: double generalAndAdministrativeExpenses: type: number format: double sellingAndMarketingExpenses: type: number format: double sellingGeneralAndAdministrativeExpenses: type: number format: double otherExpenses: type: number format: double operatingExpenses: type: number format: double costAndExpenses: type: number format: double netInterestIncome: type: number format: double interestIncome: type: number format: double interestExpense: type: number format: double depreciationAndAmortization: type: number format: double ebitda: type: number format: double ebit: type: number format: double nonOperatingIncomeExcludingInterest: type: number format: double operatingIncome: type: number format: double totalOtherIncomeExpensesNet: type: number format: double incomeBeforeTax: type: number format: double incomeTaxExpense: type: number format: double netIncomeFromContinuingOperations: type: number format: double netIncomeFromDiscontinuedOperations: type: number format: double otherAdjustmentsToNetIncome: type: number format: double netIncome: type: number format: double netIncomeDeductions: type: number format: double bottomLineNetIncome: type: number format: double eps: type: number format: double epsDiluted: type: number format: double weightedAverageShsOut: type: number format: double weightedAverageShsOutDil: type: number format: double MarketMetadataBalanceSheet: allOf: - $ref: '#/components/schemas/MarketMetadataStatementMeta' - type: object description: | One quarter of the FMP balance sheet. FMP provider only. properties: cashAndCashEquivalents: type: number format: double shortTermInvestments: type: number format: double cashAndShortTermInvestments: type: number format: double netReceivables: type: number format: double accountsReceivables: type: number format: double otherReceivables: type: number format: double inventory: type: number format: double prepaids: type: number format: double otherCurrentAssets: type: number format: double totalCurrentAssets: type: number format: double propertyPlantEquipmentNet: type: number format: double goodwill: type: number format: double intangibleAssets: type: number format: double goodwillAndIntangibleAssets: type: number format: double longTermInvestments: type: number format: double taxAssets: type: number format: double otherNonCurrentAssets: type: number format: double totalNonCurrentAssets: type: number format: double otherAssets: type: number format: double totalAssets: type: number format: double totalPayables: type: number format: double accountPayables: type: number format: double otherPayables: type: number format: double accruedExpenses: type: number format: double shortTermDebt: type: number format: double capitalLeaseObligationsCurrent: type: number format: double taxPayables: type: number format: double deferredRevenue: type: number format: double otherCurrentLiabilities: type: number format: double totalCurrentLiabilities: type: number format: double longTermDebt: type: number format: double capitalLeaseObligationsNonCurrent: type: number format: double deferredRevenueNonCurrent: type: number format: double deferredTaxLiabilitiesNonCurrent: type: number format: double otherNonCurrentLiabilities: type: number format: double totalNonCurrentLiabilities: type: number format: double otherLiabilities: type: number format: double capitalLeaseObligations: type: number format: double totalLiabilities: type: number format: double treasuryStock: type: number format: double preferredStock: type: number format: double commonStock: type: number format: double retainedEarnings: type: number format: double additionalPaidInCapital: type: number format: double accumulatedOtherComprehensiveIncomeLoss: type: number format: double otherTotalStockholdersEquity: type: number format: double totalStockholdersEquity: type: number format: double totalEquity: type: number format: double minorityInterest: type: number format: double totalLiabilitiesAndTotalEquity: type: number format: double totalInvestments: type: number format: double totalDebt: type: number format: double netDebt: type: number format: double MarketMetadataCashFlowStatement: allOf: - $ref: '#/components/schemas/MarketMetadataStatementMeta' - type: object description: | One quarter of the FMP cash-flow statement. FMP provider only. properties: netIncome: type: number format: double depreciationAndAmortization: type: number format: double deferredIncomeTax: type: number format: double stockBasedCompensation: type: number format: double changeInWorkingCapital: type: number format: double accountsReceivables: type: number format: double inventory: type: number format: double accountsPayables: type: number format: double otherWorkingCapital: type: number format: double otherNonCashItems: type: number format: double netCashProvidedByOperatingActivities: type: number format: double investmentsInPropertyPlantAndEquipment: type: number format: double acquisitionsNet: type: number format: double purchasesOfInvestments: type: number format: double salesMaturitiesOfInvestments: type: number format: double otherInvestingActivities: type: number format: double netCashProvidedByInvestingActivities: type: number format: double netDebtIssuance: type: number format: double longTermNetDebtIssuance: type: number format: double shortTermNetDebtIssuance: type: number format: double netStockIssuance: type: number format: double netCommonStockIssuance: type: number format: double commonStockIssuance: type: number format: double commonStockRepurchased: type: number format: double netPreferredStockIssuance: type: number format: double netDividendsPaid: type: number format: double commonDividendsPaid: type: number format: double preferredDividendsPaid: type: number format: double otherFinancingActivities: type: number format: double netCashProvidedByFinancingActivities: type: number format: double effectOfForexChangesOnCash: type: number format: double netChangeInCash: type: number format: double cashAtEndOfPeriod: type: number format: double cashAtBeginningOfPeriod: type: number format: double operatingCashFlow: type: number format: double capitalExpenditure: type: number format: double freeCashFlow: type: number format: double incomeTaxesPaid: type: number format: double interestPaid: type: number format: double MarketMetadataStatementMeta: type: object required: - date - symbol - reportedCurrency - cik - filingDate - acceptedDate - fiscalYear - period - fiscalQuarter description: > Common header shared by the three FMP financial statements. Mirrors FMP's statement envelope; `fiscalQuarter` is the derived "Q2 2026"- style label built from `period` + `fiscalYear`. properties: date: type: string description: ISO date of the period end (`YYYY-MM-DD`). symbol: type: string reportedCurrency: type: string cik: type: string filingDate: type: string acceptedDate: type: string fiscalYear: type: string period: type: string description: FMP fiscal period label (e.g. `Q2`). fiscalQuarter: type: string description: Derived fiscal-quarter label (e.g. `Q2 2026`). nullable: true ````