{ "openapi": "3.1.0", "info": { "description": "Read market status and discover Accounts and Instruments available to the authenticated Mapped Profile.", "title": "Portfolio Exchange External API", "version": "v1" }, "servers": [ { "url": "https://market.dev.portfolio.exchange" } ], "tags": [ { "name": "Authentication", "description": "Obtain an access token using the client credentials supplied during onboarding." }, { "description": "Discover Accounts and their current informational capabilities.", "name": "Accounts" }, { "description": "Visible Instruments and their current trading terms.", "name": "Instruments" }, { "description": "Market availability and trading-session state.", "name": "Market" } ], "paths": { "/oauth2/token": { "post": { "operationId": "getAccessToken", "summary": "Get an access token", "tags": [ "Authentication" ], "description": "Authenticate with your client ID and secret to obtain a Bearer access token.\nSend a form-encoded request with `grant_type=client_credentials` over HTTPS.\n\nThe examples use **client_secret_basic**: your client ID and secret are the\nHTTP Basic username and password. As an alternative, **client_secret_post**\nsends `client_id` and `client_secret` in the form body and omits Basic authentication.\nUse one method per request; credentials are required with either method.\n\nIn generated examples, replace `{{BASE64_CLIENT_CREDENTIALS}}` with the\nBase64 encoding of `CLIENT_ID:CLIENT_SECRET` using your onboarding credentials.\nYour HTTP library's Basic authentication option can construct this header for you.\n\nUse `expires_in` to calculate when the token expires. Reuse the token until\nyour application's renewal threshold, then request another token with the\nsame client-credentials flow. This flow returns no refresh token or ID token.\n\nToken failures use an OAuth JSON error response, separate from the API's\nproblem-details responses. See the [Cognito token endpoint documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html).\n", "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "description": "Client-credentials grant. With Basic authentication, only grant_type is needed.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "The machine-to-machine OAuth grant.", "examples": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Required with client_secret_post. Omit when using Basic authentication." }, "client_secret": { "type": "string", "format": "password", "writeOnly": true, "description": "Required with client_secret_post. Omit when using Basic authentication. Keep this value secret." } } }, "example": { "grant_type": "client_credentials" } } } }, "responses": { "200": { "description": "Access token issued. Its lifetime is reported in expires_in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAccessToken" }, "example": { "access_token": "", "token_type": "Bearer", "expires_in": 3600 } } } }, "400": { "description": "The token request could not be completed. Check the grant and client\ncredentials before retrying. A client that is not enabled for the grant\ncan produce unauthorized_client.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_client" } } } } }, "servers": [ { "url": "https://market.dev.portfolio.exchange" } ] } }, "/v1/accounts": { "get": { "description": "Lists Accounts the Mapped Profile may consult, ordered by CCV ascending. Results may include PRE_OPENING and DISABLED Accounts. Each request checks current permissions and state; the API does not keep a snapshot across pages.", "operationId": "listExternalAccounts", "parameters": [ { "description": "Maximum number of items on the first page. The default is 50. Do not send limit with cursor. Values outside 1 through 200 return 422, and malformed values return 400.", "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, { "description": "Opaque continuation cursor that retains the original page size. Send it without other query parameters. An invalid cursor returns 400 invalid-cursor.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Optional diagnostic ID. The API echoes a valid value unchanged.", "in": "header", "name": "X-Correlation-Id", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPage" } } }, "description": "Current Account page", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "invalid-request, invalid-cursor, or invalid-correlation-id: The request, cursor, or correlation ID is invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "authentication-failed: Authentication is missing or invalid.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "type": "string", "examples": [ "Bearer" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "access-denied: The authenticated identity cannot perform this request.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "405": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "method-not-allowed: The HTTP method is unsupported for this path.", "headers": { "Allow": { "required": true, "schema": { "type": "string", "examples": [ "GET" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-acceptable: The Accept header does not allow application/json.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "validation-failed: One or more request values are invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "internal-error: An unexpected server error occurred.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "service-unavailable: The service cannot complete the request at this time.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "externalOAuth2": [] } ], "summary": "List Accounts", "tags": [ "Accounts" ] } }, "/v1/accounts/{ccv}": { "get": { "description": "Returns the same representation used by Account discovery. A well-formed but unknown or inaccessible CCV returns 404. A malformed or checksum-invalid CCV returns 422. Account CCVs are stable and never reused.", "operationId": "getExternalAccount", "parameters": [ { "description": "The Account's immutable 20-digit CCV, including valid control digits.", "in": "path", "name": "ccv", "required": true, "schema": { "type": "string", "examples": [ "00321203110000000031" ], "maxLength": 20, "minLength": 20, "pattern": "^[0-9]{20}$" } }, { "description": "Optional diagnostic ID. The API echoes a valid value unchanged.", "in": "header", "name": "X-Correlation-Id", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "Current Account", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "invalid-request or invalid-correlation-id: The request syntax, query parameters, or correlation ID is invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "authentication-failed: Authentication is missing or invalid.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "type": "string", "examples": [ "Bearer" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "access-denied: The authenticated identity cannot perform this request.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-found: The Account is unknown or inaccessible.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "405": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "method-not-allowed: The HTTP method is unsupported for this path.", "headers": { "Allow": { "required": true, "schema": { "type": "string", "examples": [ "GET" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-acceptable: The Accept header does not allow application/json.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "validation-failed: One or more request values are invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "internal-error: An unexpected server error occurred.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "service-unavailable: The service cannot complete the request at this time.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "externalOAuth2": [] } ], "summary": "Get an Account", "tags": [ "Accounts" ] } }, "/v1/market/instruments": { "get": { "description": "Returns the Instruments visible to the Mapped Profile, ordered by name and then ISIN, both ascending. A continuation request supplies only the cursor.", "operationId": "listExternalMarketInstruments", "parameters": [ { "description": "Optional diagnostic ID. The API echoes a valid value unchanged.", "in": "header", "name": "X-Correlation-Id", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$" } }, { "description": "Instrument type to include.", "in": "query", "name": "type", "required": false, "schema": { "$ref": "#/components/schemas/InstrumentType" } }, { "description": "Uppercase ISO 4217 currency code.", "example": "EUR", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Instrument trading status to include.", "in": "query", "name": "tradingStatus", "required": false, "schema": { "$ref": "#/components/schemas/InstrumentTradingStatus" } }, { "description": "Case-insensitive literal substring matched against name, ISIN, or Trading Code.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of items on the first page. The default is 50.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 200, "minimum": 1 } }, { "description": "Opaque continuation cursor. Send it without filters or limit.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentCollection" } } }, "description": "Visible Instruments", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "invalid-request, invalid-cursor, or invalid-correlation-id: The request, cursor, or correlation ID is invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "authentication-failed: Authentication is missing or invalid.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "type": "string", "examples": [ "Bearer" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "access-denied: The authenticated identity cannot perform this request.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "405": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "method-not-allowed: The HTTP method is unsupported for this path.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-acceptable: The Accept header does not allow application/json.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "validation-failed: One or more query parameters are invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "internal-error: An unexpected server error occurred.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "service-unavailable: The service cannot complete the request at this time.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "externalOAuth2": [] } ], "summary": "List Instruments", "tags": [ "Instruments" ] } }, "/v1/market/instruments/{isin}": { "get": { "description": "Returns the current trading terms for one visible Instrument identified by ISIN.", "operationId": "getExternalMarketInstrument", "parameters": [ { "description": "Optional diagnostic ID. The API echoes a valid value unchanged.", "in": "header", "name": "X-Correlation-Id", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$" } }, { "description": "Canonical Instrument ISIN; lowercase input is accepted for lookup.", "example": "ES0875759518", "in": "path", "name": "isin", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstrumentDetail" } } }, "description": "Current Instrument detail", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "invalid-request or invalid-correlation-id: The ISIN, request syntax, or correlation ID is invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "authentication-failed: Authentication is missing or invalid.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "type": "string", "examples": [ "Bearer" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "access-denied: The authenticated identity cannot perform this request.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-found: The Instrument is unknown, invisible, or ineligible.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "405": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "method-not-allowed: The HTTP method is unsupported for this path.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-acceptable: The Accept header does not allow application/json.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "internal-error: An unexpected server error occurred.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "service-unavailable: The service cannot complete the request at this time.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "externalOAuth2": [] } ], "summary": "Get an Instrument", "tags": [ "Instruments" ] } }, "/v1/market/status": { "get": { "description": "Returns the current market status. changedAt records when the state began, and observedAt records when the Portfolio Exchange External API observed it.", "operationId": "getExternalMarketStatus", "parameters": [ { "description": "Optional diagnostic ID. The API echoes a valid value unchanged.", "in": "header", "name": "X-Correlation-Id", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStatus" } } }, "description": "Current market status", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "invalid-request or invalid-correlation-id: The request or correlation ID is invalid.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "authentication-failed: Authentication is missing or invalid.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "type": "string", "examples": [ "Bearer" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "access-denied: The authenticated identity cannot perform this request.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "405": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "method-not-allowed: The HTTP method is unsupported for this path.", "headers": { "Allow": { "required": true, "schema": { "type": "string", "examples": [ "GET" ] }, "style": "simple" }, "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "not-acceptable: The Accept header does not allow application/json.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "internal-error: An unexpected server error occurred.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ExternalApiProblem" } } }, "description": "service-unavailable: The service cannot complete the request at this time.", "headers": { "X-Correlation-Id": { "description": "Valid caller-supplied diagnostic ID, echoed unchanged.", "schema": { "type": "string", "maxLength": 64, "minLength": 1 } }, "X-Request-Id": { "description": "Server-generated identifier for this HTTP attempt.", "required": true, "schema": { "type": "string", "format": "uuid" } } } } }, "security": [ { "externalOAuth2": [] } ], "summary": "Get current market status", "tags": [ "Market" ] } } }, "components": { "schemas": { "Account": { "type": "object", "description": "An Account the Mapped Profile may consult. List and detail share this representation.", "properties": { "capabilities": { "type": "array", "description": "Informational abilities in WALLET_BALANCE_READ, ORDER_CREATE, ORDER_CANCEL order; may be empty. Commands always reauthorize.", "examples": [ "[\"WALLET_BALANCE_READ\",\"ORDER_CREATE\",\"ORDER_CANCEL\"]" ], "items": { "$ref": "#/components/schemas/AccountCapability" } }, "ccv": { "type": "string", "description": "Stable, immutable Account CCV that is never reused.", "examples": [ "00321203110000000031" ], "maxLength": 20, "minLength": 20, "pattern": "^[0-9]{20}$" }, "name": { "type": [ "string", "null" ], "description": "Account name exactly as stored, including blank values or null.", "examples": [ "Treasury" ] }, "observedAt": { "type": "string", "format": "date-time", "description": "UTC observation time, shared by all Accounts on this page. Each page is a new observation.", "examples": [ "2026-09-21T10:11:12.123456Z" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$" }, "omnibus": { "type": "boolean", "description": "Whether the Account is omnibus.", "examples": [ "false" ] }, "status": { "$ref": "#/components/schemas/AccountStatus", "description": "Current Account lifecycle status. Non-active Accounts remain discoverable when authorized.", "examples": [ "ACTIVE" ] } }, "required": [ "capabilities", "ccv", "name", "observedAt", "omnibus", "status" ] }, "AccountCapability": { "type": "string", "description": "Balance consultation is independent of Account status; order creation and cancellation require ACTIVE status and their respective relation permissions.", "enum": [ "WALLET_BALANCE_READ", "ORDER_CREATE", "ORDER_CANCEL" ] }, "AccountPage": { "type": "object", "description": "Authorized Accounts in CCV ascending order, observed independently on every page.", "properties": { "items": { "type": "array", "description": "The authorized Accounts on this page; empty when none match.", "items": { "$ref": "#/components/schemas/Account" } }, "page": { "$ref": "#/components/schemas/PageMetadata", "description": "Continuation metadata; nextCursor is null exactly when hasMore is false." } }, "required": [ "items", "page" ] }, "AccountStatus": { "type": "string", "description": "Account lifecycle states.", "enum": [ "PRE_OPENING", "ACTIVE", "DISABLED" ] }, "AccrualDayType": { "type": "string", "description": "Supported type of days used for interest accrual.", "enum": [ "CALENDAR_DAYS", "WORKING_DAYS" ] }, "CouponPeriodicity": { "type": "string", "description": "Supported coupon payment frequency.", "enum": [ "WEEKLY", "MONTHLY", "QUARTERLY", "BIANNUAL", "ANNUAL" ] }, "DayCountConvention": { "type": "string", "description": "Supported interest day-count convention.", "enum": [ "ACTUAL_ACTUAL", "ACTUAL_360", "ACTUAL_365", "THIRTY_360_EUROPEAN", "THIRTY_360_AMERICAN" ] }, "DebtInstrumentTradingRules": { "type": "object", "description": "Current order constraints for a debt Instrument.", "properties": { "tickSize": { "type": "string", "description": "Positive percentage price increment encoded as a base-10 JSON string. It has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "0.001" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "warningThresholds": { "$ref": "#/components/schemas/DebtInstrumentWarningThresholds", "description": "Order values that require warning acknowledgement before submission." } }, "required": [ "tickSize", "warningThresholds" ] }, "DebtInstrumentWarningThresholds": { "type": "object", "description": "Warning thresholds expressed in the Instrument currency.", "properties": { "nominalValue": { "$ref": "#/components/schemas/Money", "description": "Non-negative nominal-value threshold in the Instrument currency. The source scale is preserved, and V1 defines no separate total-digit limit." }, "totalOrderAmount": { "$ref": "#/components/schemas/Money", "description": "Non-negative total-order-amount threshold in the Instrument currency. The source scale is preserved, and V1 defines no separate total-digit limit." } }, "required": [ "nominalValue", "totalOrderAmount" ] }, "EquityInstrumentDetail": { "type": "object", "description": "Current trading detail for an equity Instrument.", "properties": { "accruedInterest": { "type": [ "string", "null" ], "description": "Accrued interest, always null for equity Instruments.", "examples": [ "0" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "description": { "type": "string", "description": "Public Instrument description.", "examples": [ "Ordinary registered shares" ] }, "instrument": { "$ref": "#/components/schemas/InstrumentSummary", "description": "Instrument summary at observedAt." }, "issuerDescription": { "type": [ "string", "null" ], "description": "Public issuer description, or null when none is published.", "examples": [ "European renewable energy producer" ] }, "lastPrice": { "$ref": "#/components/schemas/Money", "description": "Current trading baseline in the Instrument currency. It equals the approved reference price until the first matched trade, then the most recent matched price. The JSON string preserves the source scale and may contain trailing zeros beyond instrument.priceDecimals. Ignoring trailing zeros, it has at most instrument.priceDecimals fractional digits." }, "maturityDate": { "type": [ "string", "null" ], "format": "date", "description": "Always null for equity Instruments.", "examples": [ "null" ] }, "referencePrice": { "$ref": "#/components/schemas/Money", "description": "Positive reference price in the Instrument currency. The JSON string preserves the source scale and may contain trailing zeros beyond instrument.priceDecimals. Ignoring trailing zeros, it has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit." }, "terms": { "$ref": "#/components/schemas/EquityInstrumentTerms", "description": "Current equity issuance terms." }, "tradingRules": { "$ref": "#/components/schemas/EquityInstrumentTradingRules", "description": "Current equity order constraints." }, "tradingStartDate": { "type": "string", "format": "date", "description": "Date on which trading started.", "examples": [ "2026-09-01" ] } }, "required": [ "accruedInterest", "description", "instrument", "issuerDescription", "lastPrice", "maturityDate", "referencePrice", "terms", "tradingRules", "tradingStartDate" ] }, "EquityInstrumentTerms": { "type": "object", "description": "Current issuance terms for an equity Instrument.", "properties": { "issuedQuantity": { "type": "string", "description": "Positive total issued quantity encoded as a base-10 JSON string. It has at most instrument.quantityDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "1000000" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "type": { "$ref": "#/components/schemas/InstrumentType", "description": "Discriminator for equity terms.", "enum": [ "EQUITY" ] } }, "required": [ "issuedQuantity", "type" ] }, "EquityInstrumentTradingRules": { "type": "object", "description": "Current order constraints for an equity Instrument.", "properties": { "tickSize": { "$ref": "#/components/schemas/Money", "description": "Positive price increment in the Instrument currency. amount has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit." }, "warningThresholds": { "$ref": "#/components/schemas/EquityInstrumentWarningThresholds", "description": "Order values that require warning acknowledgement before submission." } }, "required": [ "tickSize", "warningThresholds" ] }, "EquityInstrumentWarningThresholds": { "type": "object", "description": "Quantity and monetary warning thresholds for equity orders.", "properties": { "quantity": { "type": "string", "description": "Non-negative quantity threshold encoded as a base-10 JSON string. It has at most instrument.quantityDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "100000" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "totalOrderAmount": { "$ref": "#/components/schemas/Money", "description": "Non-negative total-order-amount threshold in the Instrument currency. The source scale is preserved, and V1 defines no separate total-digit limit." } }, "required": [ "quantity", "totalOrderAmount" ] }, "ExternalApiProblem": { "type": "object", "description": "RFC 9457 problem details returned by the External API.", "properties": { "code": { "type": "string", "description": "Stable machine-readable problem code.", "enum": [ "invalid-request", "invalid-cursor", "invalid-correlation-id", "authentication-failed", "access-denied", "not-found", "method-not-allowed", "not-acceptable", "unsupported-media-type", "validation-failed", "conflict", "service-unavailable", "internal-error" ], "examples": [ "authentication-failed" ] }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence.", "examples": [ "The bearer token is missing or invalid." ] }, "instance": { "type": "string", "format": "uri", "description": "URI identifying this specific problem occurrence.", "examples": [ "urn:uuid:b495f901-5456-4df6-a4da-cc750638c66b" ] }, "requestId": { "type": "string", "format": "uuid", "description": "Server-generated identifier used to correlate this HTTP attempt.", "examples": [ "b495f901-5456-4df6-a4da-cc750638c66b" ] }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code for this occurrence.", "examples": [ "401" ] }, "title": { "type": "string", "description": "Short, human-readable summary of the problem category.", "examples": [ "Authentication failed" ] }, "type": { "type": "string", "format": "uri", "description": "Stable URI identifying the problem category.", "examples": [ "https://docs.portfolio.exchange/external-api/v1/problems/authentication-failed" ] }, "violations": { "type": [ "array", "null" ], "description": "Field-level violations, or null when the problem is not a validation failure.", "items": { "$ref": "#/components/schemas/ExternalApiViolation" } } }, "required": [ "code", "detail", "instance", "requestId", "status", "title", "type", "violations" ] }, "ExternalApiViolation": { "type": "object", "description": "A field-level validation failure.", "properties": { "code": { "type": "string", "description": "Stable machine-readable validation code.", "examples": [ "invalid-format" ] }, "detail": { "type": "string", "description": "Human-readable explanation of the validation failure.", "examples": [ "Must be an ISO 4217 alphabetic currency code." ] }, "pointer": { "type": "string", "description": "JSON Pointer locating the invalid request value.", "examples": [ "/currency" ] } }, "required": [ "code", "detail", "pointer" ] }, "FixedCouponDebtInstrumentDetail": { "type": "object", "description": "Current trading detail for a fixed-coupon debt Instrument.", "properties": { "accruedInterest": { "type": "string", "description": "Non-negative accrued interest as a percentage of nominal value, encoded as a base-10 JSON string. It has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "1.1250" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "description": { "type": "string", "description": "Public Instrument description.", "examples": [ "Five-year senior unsecured notes" ] }, "instrument": { "$ref": "#/components/schemas/InstrumentSummary", "description": "Instrument summary at observedAt." }, "issuerDescription": { "type": [ "string", "null" ], "description": "Public issuer description, or null when none is published.", "examples": [ "European renewable energy producer" ] }, "lastPrice": { "type": "string", "description": "Current clean trading baseline as a percentage of nominal value. It equals the approved reference price until the first matched trade, then the most recent clean matched price. The base-10 JSON string has at most instrument.priceDecimals fractional digits.", "examples": [ "99.5000" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "maturityDate": { "type": "string", "format": "date", "description": "Contractual maturity date.", "examples": [ "2031-09-01" ] }, "referencePrice": { "type": "string", "description": "Positive clean reference price as a percentage of nominal value, encoded as a base-10 JSON string. It has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "99.2500" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "terms": { "$ref": "#/components/schemas/FixedCouponDebtInstrumentTerms", "description": "Current fixed-coupon debt issuance terms." }, "tradingRules": { "$ref": "#/components/schemas/DebtInstrumentTradingRules", "description": "Current debt order constraints." }, "tradingStartDate": { "type": "string", "format": "date", "description": "Date on which trading started.", "examples": [ "2026-09-01" ] } }, "required": [ "accruedInterest", "description", "instrument", "issuerDescription", "lastPrice", "maturityDate", "referencePrice", "terms", "tradingRules", "tradingStartDate" ] }, "FixedCouponDebtInstrumentTerms": { "type": "object", "description": "Current issuance and coupon terms for a fixed-coupon debt Instrument.", "properties": { "accrualDayType": { "$ref": "#/components/schemas/AccrualDayType", "description": "Type of days used for accrual." }, "couponPeriodicity": { "$ref": "#/components/schemas/CouponPeriodicity", "description": "Coupon payment frequency." }, "currentNominalValue": { "type": "string", "description": "Positive nominal value per unit in the Instrument currency, encoded as a base-10 JSON string. The source scale is preserved, and V1 defines no separate total-digit limit.", "examples": [ "1000.00" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "dayCountConvention": { "$ref": "#/components/schemas/DayCountConvention", "description": "Interest day-count convention." }, "firstCouponDate": { "type": [ "string", "null" ], "format": "date", "description": "First coupon payment date, or null when not defined.", "examples": [ "2027-03-01" ] }, "fixedCouponPercentage": { "type": "string", "description": "Positive annual coupon percentage encoded as a base-10 JSON string. The source scale is preserved, and V1 defines no separate total-digit limit.", "examples": [ "5.2500" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "initialAccrualDate": { "type": "string", "format": "date", "description": "Date from which interest starts accruing.", "examples": [ "2026-09-01" ] }, "type": { "$ref": "#/components/schemas/InstrumentType", "description": "Discriminator for fixed-coupon debt terms.", "enum": [ "FIXED_COUPON_DEBT" ] } }, "required": [ "accrualDayType", "couponPeriodicity", "currentNominalValue", "dayCountConvention", "firstCouponDate", "fixedCouponPercentage", "initialAccrualDate", "type" ] }, "InstrumentCollection": { "type": "object", "description": "A cursor page of visible Market Instruments.", "properties": { "items": { "type": "array", "description": "Visible Instruments in stable name and ISIN order.", "items": { "$ref": "#/components/schemas/InstrumentSummary", "description": "Visible Instruments in stable name and ISIN order." } }, "page": { "$ref": "#/components/schemas/PageMetadata", "description": "Continuation information for this page." } }, "required": [ "items", "page" ] }, "InstrumentDetail": { "description": "Instrument details. The Instrument type selects the response schema.", "oneOf": [ { "$ref": "#/components/schemas/EquityInstrumentDetail" }, { "$ref": "#/components/schemas/FixedCouponDebtInstrumentDetail" }, { "$ref": "#/components/schemas/ZeroCouponDebtInstrumentDetail" } ] }, "InstrumentIssuer": { "type": "object", "description": "Organization identity of the issuer.", "properties": { "lei": { "type": "string", "description": "Issuer Legal Entity Identifier.", "examples": [ "529900T8BM49AURSDO55" ] }, "name": { "type": "string", "description": "Issuer Organization name.", "examples": [ "Issuer SA" ] } }, "required": [ "lei", "name" ] }, "InstrumentSummary": { "type": "object", "description": "Instrument summary at observedAt.", "properties": { "currency": { "type": "string", "description": "Uppercase ISO 4217 trading currency.", "examples": [ "EUR" ] }, "isin": { "type": "string", "description": "Canonical International Securities Identification Number.", "examples": [ "ES0875759518" ] }, "issuer": { "$ref": "#/components/schemas/InstrumentIssuer", "description": "Issuer identity." }, "name": { "type": "string", "description": "Public Instrument name.", "examples": [ "Alpha Energy" ] }, "observedAt": { "type": "string", "format": "date-time", "description": "UTC observation time shared by the current Instrument snapshot.", "examples": [ "2026-09-15T14:30:00.123456Z" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$" }, "priceDecimals": { "type": "integer", "format": "int32", "description": "Maximum number of fractional digits for prices.", "examples": [ "2" ], "minimum": 0 }, "professionalOnly": { "type": "boolean", "description": "Whether trading is restricted to professional investors.", "examples": [ "false" ] }, "quantityDecimals": { "type": "integer", "format": "int32", "description": "Maximum number of fractional digits for quantities.", "examples": [ "4" ], "minimum": 0 }, "tradingCode": { "type": "string", "description": "Trading code assigned to the Instrument.", "examples": [ "ALP" ] }, "tradingStatus": { "$ref": "#/components/schemas/InstrumentTradingStatus", "description": "Current Instrument trading status." }, "type": { "$ref": "#/components/schemas/InstrumentType", "description": "Supported Instrument type." } }, "required": [ "currency", "isin", "issuer", "name", "observedAt", "priceDecimals", "professionalOnly", "quantityDecimals", "tradingCode", "tradingStatus", "type" ] }, "InstrumentTradingStatus": { "type": "string", "description": "Current Instrument-specific trading availability.", "enum": [ "TRADABLE", "HALTED", "SUSPENDED", "NOT_TRADABLE" ] }, "InstrumentType": { "type": "string", "description": "Supported Market Instrument classification.", "enum": [ "EQUITY", "FIXED_COUPON_DEBT", "ZERO_COUPON_DEBT" ] }, "MarketStatus": { "type": "object", "description": "Current trading-session state of the Portfolio Exchange market.", "properties": { "changedAt": { "type": "string", "format": "date-time", "description": "UTC instant at which the current market state began.", "examples": [ "2026-09-03T10:11:12.123456Z" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$" }, "observedAt": { "type": "string", "format": "date-time", "description": "UTC instant at which the Portfolio Exchange External API observed the current state.", "examples": [ "2026-09-03T10:12:13.654321Z" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$" }, "status": { "$ref": "#/components/schemas/MarketTradingStatus", "description": "Whether the market currently accepts trading activity.", "examples": [ "OPEN" ] } }, "required": [ "changedAt", "observedAt", "status" ] }, "MarketTradingStatus": { "type": "string", "description": "Trading availability reported by Portfolio Exchange.", "enum": [ "OPEN", "CLOSED" ] }, "Money": { "type": "object", "description": "Exact monetary amount in an ISO 4217 currency.", "properties": { "amount": { "type": "string", "description": "Base-10 amount in currency, encoded as a JSON string without exponent notation. The containing field defines the permitted sign and scale. V1 defines no separate total-digit limit.", "examples": [ "125000.00" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "currency": { "type": "string", "description": "Uppercase ISO 4217 currency code.", "examples": [ "EUR" ] } }, "required": [ "amount", "currency" ] }, "PageMetadata": { "type": "object", "description": "Continuation metadata for a cursor-paginated collection.", "properties": { "hasMore": { "type": "boolean", "description": "Whether another page is available.", "examples": [ "true" ] }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when this is the final page.", "examples": [ "active.eyJhcGlNYWpvciI6InYxIn0.signature" ] } }, "required": [ "hasMore", "nextCursor" ] }, "ZeroCouponDebtInstrumentDetail": { "type": "object", "description": "Current trading detail for a zero-coupon debt Instrument.", "properties": { "accruedInterest": { "type": "string", "description": "Non-negative accrued interest as a percentage of nominal value, encoded as a base-10 JSON string. It has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "0" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "description": { "type": "string", "description": "Public Instrument description.", "examples": [ "Three-year zero-coupon notes" ] }, "instrument": { "$ref": "#/components/schemas/InstrumentSummary", "description": "Instrument summary at observedAt." }, "issuerDescription": { "type": [ "string", "null" ], "description": "Public issuer description, or null when none is published.", "examples": [ "European renewable energy producer" ] }, "lastPrice": { "type": "string", "description": "Current clean trading baseline as a percentage of nominal value. It equals the approved reference price until the first matched trade, then the most recent clean matched price. The base-10 JSON string has at most instrument.priceDecimals fractional digits.", "examples": [ "95.5000" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "maturityDate": { "type": "string", "format": "date", "description": "Contractual maturity date.", "examples": [ "2029-09-01" ] }, "referencePrice": { "type": "string", "description": "Positive clean reference price as a percentage of nominal value, encoded as a base-10 JSON string. It has at most instrument.priceDecimals fractional digits. V1 defines no separate total-digit limit.", "examples": [ "95.2500" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "terms": { "$ref": "#/components/schemas/ZeroCouponDebtInstrumentTerms", "description": "Current zero-coupon debt issuance terms." }, "tradingRules": { "$ref": "#/components/schemas/DebtInstrumentTradingRules", "description": "Current debt order constraints." }, "tradingStartDate": { "type": "string", "format": "date", "description": "Date on which trading started.", "examples": [ "2026-09-01" ] } }, "required": [ "accruedInterest", "description", "instrument", "issuerDescription", "lastPrice", "maturityDate", "referencePrice", "terms", "tradingRules", "tradingStartDate" ] }, "ZeroCouponDebtInstrumentTerms": { "type": "object", "description": "Current issuance terms for a zero-coupon debt Instrument.", "properties": { "currentNominalValue": { "type": "string", "description": "Positive nominal value per unit in the Instrument currency, encoded as a base-10 JSON string. The source scale is preserved, and V1 defines no separate total-digit limit.", "examples": [ "1000.00" ], "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "type": { "$ref": "#/components/schemas/InstrumentType", "description": "Discriminator for zero-coupon debt terms.", "enum": [ "ZERO_COUPON_DEBT" ] } }, "required": [ "currentNominalValue", "type" ] }, "OAuthAccessToken": { "type": "object", "description": "An access token for authenticated API requests.", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "Access token to send in the Authorization Bearer header. Treat it as a secret.", "examples": [ "" ] }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "The HTTP authorization scheme for API requests." }, "expires_in": { "type": "integer", "minimum": 1, "description": "Token lifetime in seconds. Use this value rather than assuming a fixed lifetime.", "examples": [ 3600 ] } } }, "OAuthError": { "type": "object", "description": "OAuth token error. This is separate from the resource API's problem-details schema.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "OAuth error code, such as invalid_request, invalid_client, invalid_grant, unauthorized_client or unsupported_grant_type.", "examples": [ "invalid_client" ] }, "error_description": { "type": "string", "description": "Additional explanation when provided by the authorization service." } } } }, "securitySchemes": { "clientSecretBasic": { "type": "http", "scheme": "basic", "description": "Client ID as the username and client secret as the password, sent over HTTPS. Form-body credentials are an alternative on the token endpoint." }, "externalOAuth2": { "type": "oauth2", "description": "Obtain an access token with your client credentials, then send Authorization Bearer on API requests over HTTPS. Access is configured during onboarding.", "flows": { "clientCredentials": { "tokenUrl": "https://market.dev.portfolio.exchange/oauth2/token", "scopes": {} } } } } }, "x-problem-statuses": { "access-denied": 403, "authentication-failed": 401, "conflict": 409, "internal-error": 500, "invalid-correlation-id": 400, "invalid-cursor": 400, "invalid-request": 400, "method-not-allowed": 405, "not-acceptable": 406, "not-found": 404, "service-unavailable": 503, "unsupported-media-type": 415, "validation-failed": 422 } }