--- title: "Create swap order" method: POST path: "/v0/swap-orders/" tags: ["Swap orders"] --- # Create swap order `POST /v0/swap-orders/` ## Request - Base URL: `https://distributor-api.spiko.io` - URL: `https://distributor-api.spiko.io/v0/swap-orders/` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) **Move an investor's holdings directly from one share class to another. This is materialized by a linked redemption/subscription pair.** - `accountId` must belong to `investorId` and must already hold an active line for `toShareClassId`; otherwise the order is rejected with `MissingAccountLineError`. Add the line with [POST /v0/accounts/{accountId}/lines](#tag/Accounts/operation/accounts.addAccountLine) and retry. - The `quantity` field supports three modes: - `{"mode":"amount","amount":{"value":"1000","currency":"USD"}}` - swap a specific amount - `{"mode":"shares","shares":"10.5"}` - swap a specific number of shares - `{"mode":"total"}` - swap the whole position - In `amount` mode, `amount.currency` **must** be the currency of `fromShareClassId` (`USD` for `SAFO`, `EUR` for `eurSAFO`, and so on). Any other currency, including the target share class currency, is rejected with an `ApplicationError` carrying `customErrorCode: "CurrencyNotSupported"`. A swap is always sized on the side it leaves from; the conversion to the target currency happens at execution. - Not every pair of share classes can be swapped. An unavailable pair is rejected with `SwapNotAvailableError`, whose `reason` says why (`share-classes-not-swappable`, `no-conversion-path`, …). - Where the two share classes are denominated in different currencies, the conversion is applied at execution using that day's rate. The rate is not known when the order is created, so it appears in `settlement.exchangeRate` only once the order reaches `executed`. - The order stays `created` until both sides have been valued, then becomes `executed` and carries a `settlement` with both sides' amounts, shares and applied NAVs. Depending on the funds involved, the two sides are valued either on the same day or a few business days apart. > **Distribute-with-Spiko's-license distributors** cannot place this order. Swap orders are not yet available through an [Investor JWT](/developers/distributor_api/technical_guides/investor_jwt). ## Request body - object - `investorId` string, uuid, required: a Universally Unique Identifier - `accountId` string, uuid, required: a Universally Unique Identifier - `fromShareClassId` string, uuid, required: a Universally Unique Identifier - `toShareClassId` string, uuid, required: a Universally Unique Identifier - `quantity` union, required - object - `mode` 'amount', required - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - object - `mode` 'shares', required - `shares` string, required - object - `mode` 'total', required ## Response `200` Success - union - object - `id` string, uuid, required: a Universally Unique Identifier - `investorId` string, uuid, required: a Universally Unique Identifier - `accountId` string, uuid, required: a Universally Unique Identifier - `fromShareClassId` string, uuid, required: a Universally Unique Identifier - `toShareClassId` string, uuid, required: a Universally Unique Identifier - `quantity` union, required - object - `mode` 'amount', required - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - object - `mode` 'shares', required - `shares` string, required - object - `mode` 'total', required - `createdAt` string, required - `status` 'created', required - object - `id` string, uuid, required: a Universally Unique Identifier - `investorId` string, uuid, required: a Universally Unique Identifier - `accountId` string, uuid, required: a Universally Unique Identifier - `fromShareClassId` string, uuid, required: a Universally Unique Identifier - `toShareClassId` string, uuid, required: a Universally Unique Identifier - `quantity` union, required - object - `mode` 'amount', required - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - object - `mode` 'shares', required - `shares` string, required - object - `mode` 'total', required - `createdAt` string, required - `status` 'executed', required - `executedAt` string, required - `settlement` object, required - `source` object, required - `shareClassId` string, uuid, required: a Universally Unique Identifier - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `sharesAmount` string, required - `appliedNAV` object, required - `day` string, required: a day in ISO format "YYYY-MM-DD" - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `target` object, required - `shareClassId` string, uuid, required: a Universally Unique Identifier - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `sharesAmount` string, required - `appliedNAV` object, required - `day` string, required: a day in ISO format "YYYY-MM-DD" - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `exchangeRate` object, nullable, required - `fundId` string, uuid, required: a Universally Unique Identifier - `day` string, required: a day in ISO format "YYYY-MM-DD" - `baseCurrency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `quoteCurrency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - `fxRate` string, required - object - `id` string, uuid, required: a Universally Unique Identifier - `investorId` string, uuid, required: a Universally Unique Identifier - `accountId` string, uuid, required: a Universally Unique Identifier - `fromShareClassId` string, uuid, required: a Universally Unique Identifier - `toShareClassId` string, uuid, required: a Universally Unique Identifier - `quantity` union, required - object - `mode` 'amount', required - `amount` NonNegativeAmount, required - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92" - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK" - object - `mode` 'shares', required - `shares` string, required - object - `mode` 'total', required - `createdAt` string, required - `status` 'canceled', required - `canceledAt` string, required - `canceledBy` 'admin' | 'distributor' | 'investor' | 'system', required ## Other responses - `400`: Application Error | Insufficient balance in account to process requested operation | This pair of share classes cannot be swapped. `reason` says why. | The target account holds no active line for this share class. Add one first, then retry the swap. | The request did not match the expected schema - `401`: Authentication failed. Two bodies are possible: the schema below when the API rejects the credentials, and `{ "error": { "code", "status", "request", "message" } }` when the API gateway rejects them first. Only the former carries a `_tag`. - `403`: Forbidden - `404`: NotFound - `409`: A fixed-term line is funded once, at its opening - `503`: The investor is undergoing a scheduled upgrade, access is temporarily paused to ensure data safety. --- [API](https://skmtc.dev/spiko/apis/spiko-distributor-api.md) - [All operations](https://skmtc.dev/spiko/apis/spiko-distributor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spiko/apis/spiko-distributor-api/revisions/ad85137fd00b?raw)