openapi: 3.0.0 info: title: Embed REST API version: '2025-04-25' description: Payward Embed REST API servers: - url: https://nexus.kraken.com description: Production Server security: - API-Key: [] API-Sign: [] tags: - name: Users - name: Subaccounts - name: Verifications - name: Assets - name: Quotes - name: Portfolios - name: Earn - name: Transfers - name: Reports - name: Webhooks description: > Webhooks allow you to receive real-time notifications when events occur in Payward Embed. When you register a webhook, Payward will send HTTP POST requests to your configured URL whenever subscribed events are triggered. ## Getting Started 1. **Make sure your callback domain is allowlisted** before registering a webhook 2. **Register a webhook** using the Register Webhook endpoint — you can optionally specify `enabled` and `events` at registration time 3. **Store your secret** - the webhook secret is only returned once during registration 4. **Enable and subscribe to events** using the Update Webhook endpoint (if not configured at registration) 5. **Implement signature verification** in your webhook handler — see Webhook Events for details ## Event Types | Event Type | Description | |------------|-------------| | `custom_order.executed` | A custom_order has been successfully executed | | `custom_order.execution_failed` | A custom_order execution has failed | | `custom_order.cancelled` | A custom_order was cancelled | | `quote.executed` | A quote has been successfully executed | | `quote.execution_failed` | A quote execution has failed | | `quote.cancelled` | A quote was cancelled before execution | | `deposit.status_updated` | The status of a deposit has been updated | | `withdrawal.status_updated` | The status of a withdrawal has been updated | | `user.verified` | A user has been verified and can now trade on the platform | | `user.closed` | A user's account has been permanently closed | | `user.disabled` | A user's account has been disabled (e.g., due to a trade lock or account suspension) | | `reward.paid` | An Earn reward has been paid to a user | | `webhook.test` | A test event sent via the Test Webhook endpoint | ## Retry Behavior Payward automatically retries failed webhook deliveries using exponential backoff. The system will continue retrying until the configured timeout is reached: - **Production**: Retries for up to **5 minutes** After the retry timeout is exceeded, the webhook delivery is marked as failed and no further attempts are made. ## Best Practices - **Respond quickly** - Return a 2xx status code within 30 seconds to acknowledge receipt - **Process asynchronously** - If your processing takes time, queue the webhook for background processing - **Be idempotent** - Webhooks may be delivered more than once - **Monitor failures** - Track non-2xx responses and implement alerting paths: /b2b/assets: get: operationId: listEmbedAssets tags: - Assets summary: List Assets description: > List all assets available on the platform. This endpoint returns a list of all assets available on the platform. The response includes the asset identifier, the type of the asset, and the status of the asset on the platform. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserFilter' description: | If provided, filters the list of assets to only include those that can be traded by the user with the given IIBAN. - $ref: '#/components/parameters/AssetsFilter' description: | If provided, filters the list of assets to only include those with the given asset IDs. - in: query name: filter[platform_statuses][] description: | If provided, filters the list of assets to only include those with any of the given platform statuses. schema: type: array default: [] items: $ref: '#/components/schemas/PlatformStatus' style: form explode: true - in: query name: filter[tradable_only] description: > If provided and set to `true`, filters the list of assets to only include those that are tradable on the platform. This is equivalent to `filter[platform_statuses][]=enabled` and is provided as a convenience. schema: type: boolean default: false - in: query name: sort schema: default: market_cap_rank title: Sort Order type: string enum: - trending - market_cap_rank - '-market_cap_rank' - symbol - '-symbol' - name - '-name' - change_percent_1h - '-change_percent_1h' - change_percent_24h - '-change_percent_24h' - change_percent_7d - '-change_percent_7d' - change_percent_30d - '-change_percent_30d' - change_percent_1y - '-change_percent_1y' - listing_date - '-listing_date' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/Quote' - $ref: '#/components/parameters/Lang' responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: assets: description: The list of matching assets. type: array items: type: object properties: id: description: The asset identifier. $ref: '#/components/schemas/AssetName' disabled_against: type: array items: $ref: '#/components/schemas/AssetName' description: > If a user IIBAN was provided in the request, this field will contain a list of assets that can't be paired with this asset. decimals: description: > The maximum number of decimals that can be used for this asset. $ref: '#/components/schemas/Uint8' display_decimals: description: > The number of decimals to display for this asset. $ref: '#/components/schemas/Uint8' collateral_value: description: | Valuation as margin collateral (if applicable). type: number format: float user_status: description: > If a user id was provided in the request, this field will contain the status of the asset for the given user. anyOf: - title: Known User Status type: string enum: - tradable - available_soon - temporarily_disabled - disabled - title: Unknown User Status type: string simple_trade_decimals: $ref: '#/components/schemas/Uint8' platform_status: $ref: '#/components/schemas/PlatformStatus' english_name: $ref: '#/components/schemas/EnglishName' circulating_supply: $ref: '#/components/schemas/BigDecimal' circulating_supply_value: $ref: '#/components/schemas/BigDecimal' total_supply: $ref: '#/components/schemas/TotalSupply' total_supply_value: $ref: '#/components/schemas/BigDecimal' description: > The value of the total number of tokens that currently exist, in the `quote` asset provided in the request. max_supply: $ref: '#/components/schemas/MaxSupply' max_supply_value: $ref: '#/components/schemas/BigDecimal' description: > The value of the maximum number of tokens that can ever exist, in the `quote` asset provided in the request. price: $ref: '#/components/schemas/BigDecimal' description: > The latest price of the asset, in the `quote` asset provided in the request. trending_rank: $ref: '#/components/schemas/Uint32' description: > The trending rank of the asset compared to all other trending assets. market_cap_rank: $ref: '#/components/schemas/Uint32' description: > The rank of the asset based on the total market cap value. market_cap_value: $ref: '#/components/schemas/MarketCapValue' dominance_percent: $ref: '#/components/schemas/Percentage' description: | The market cap dominance percentage. change_percent_1h: $ref: '#/components/schemas/Percentage' description: > The price change percentage over the last 1 hour. change_percent_24h: $ref: '#/components/schemas/Percentage' description: > The price change percentage over the last 24 hours. change_percent_7d: $ref: '#/components/schemas/Percentage' description: > The price change percentage over the last 7 days. change_percent_30d: $ref: '#/components/schemas/Percentage' description: > The price change percentage over the last 30 days. change_percent_1y: $ref: '#/components/schemas/Percentage' description: > The price change percentage over the last 1 year. volume_value_24h: $ref: '#/components/schemas/BigDecimal' description: > The trading volume for the asset, in the `quote` asset provided in the request. listing_date: $ref: '#/components/schemas/Date' description: | The date the asset was first listed on Payward. ath_value: $ref: '#/components/schemas/AthValue' ath_date: $ref: '#/components/schemas/AthDate' links: type: object properties: self: type: object properties: href: type: string type: nullable: true type: string required: - href logo: $ref: '#/components/schemas/Logo' required: - logo - self required: - decimals - disabled_against - display_decimals - id - links - platform_status links: type: object properties: self: $ref: '#/components/schemas/Uri' first: $ref: '#/components/schemas/Uri' last: $ref: '#/components/schemas/Uri' prev: $ref: '#/components/schemas/Uri' next: $ref: '#/components/schemas/Uri' meta: type: object properties: total_items: $ref: '#/components/schemas/Uint32' total_pages: $ref: '#/components/schemas/Uint32' page_size: $ref: '#/components/schemas/PageSize' page_number: $ref: '#/components/schemas/PageNumber' required: - assets - links - meta '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/assets/{asset}: get: operationId: getEmbedAsset summary: Get Asset tags: - Assets description: | Get information about a specific asset. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/AssetPath' - $ref: '#/components/parameters/Quote' - $ref: '#/components/parameters/Lang' responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: symbol: $ref: '#/components/schemas/AssetName' english_name: $ref: '#/components/schemas/EnglishName' description: type: string bearish_insights: type: string bullish_insights: type: string circulating_supply: $ref: '#/components/schemas/BigDecimal' total_supply: $ref: '#/components/schemas/BigDecimal' max_supply: $ref: '#/components/schemas/BigDecimal' market_cap_value: $ref: '#/components/schemas/BigDecimal' dominance_percent: $ref: '#/components/schemas/Percentage' description: | The market cap dominance percentage. market_cap_rank: $ref: '#/components/schemas/Uint32' description: > The rank of the asset based on the total market cap value. change_value_24h: $ref: '#/components/schemas/BigDecimal' change_percent_24h: $ref: '#/components/schemas/Percentage' volume_value_24h: $ref: '#/components/schemas/BigDecimal' ath_value: $ref: '#/components/schemas/AthValue' ath_date: $ref: '#/components/schemas/AthDate' links: type: object properties: self: type: object properties: href: type: string type: nullable: true type: string required: - href logo: $ref: '#/components/schemas/Logo' required: - logo - self required: - english_name - links - symbol '400': description: | Bad Request. Error codes: - `ENexus:Unknown quote asset` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '400' code: ENexus:Unknown quote asset detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/assets/{asset}/rates: get: operationId: listEmbedAssetRates summary: List Asset Rates tags: - Assets description: > Returns historical rates for a given asset. This endpoint returns historical rates for a given asset. The response includes the timestamp for the period the rate is for and the median price of the asset during the period (daily). parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/AssetPath' - $ref: '#/components/parameters/Quote' - in: query name: start_time description: A RFC 3339 datetime deprecated: false example: '2025-06-30T00:00:00.000Z' schema: type: string format: date-time nullable: true style: form allowEmptyValue: true - in: query name: end_time description: A RFC 3339 datetime deprecated: false example: '2025-06-30T00:00:00.000Z' schema: type: string format: date-time nullable: true style: form allowEmptyValue: true - in: query name: interval description: > If provided, shows the history of the asset in the given interval. Should be in the format of an [ISO 8601 duration]. Supported resolutions: 1min, 5min, 15min, 30min, 60min, 4H, 1D, 7D, 15D deprecated: false example: PT15M schema: type: string format: duration nullable: true style: form allowEmptyValue: true responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: rates: description: List of historical records type: array items: $ref: '#/components/schemas/PriceTick' meta: type: object properties: page_oldest_rate: $ref: '#/components/schemas/PriceTick' page_newest_rate: $ref: '#/components/schemas/PriceTick' page_price_change_value: $ref: '#/components/schemas/BigDecimal' page_price_change_percent: $ref: '#/components/schemas/Percentage' required: - meta - rates '400': description: | Bad Request. Error codes: - `ENexus:Unknown base asset` — not retryable - `ENexus:Unknown quote asset` — not retryable - `ENexus:Interval is too large` — not retryable - `ENexus:Invalid start time` — not retryable - `ENexus:Invalid end time` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_base_asset: summary: Unknown base asset value: errors: - status: '400' code: ENexus:Unknown base asset detail: null result: null interval_too_large: summary: Interval is too large value: errors: - status: '400' code: ENexus:Interval is too large detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/earn/{user}: get: operationId: getEmbedEarnSummary tags: - Earn summary: Get Earn Summary description: > Get Earn summary of a user. Modifiers: user-preferred currency (quote). Response holds total amounts (all-time). For per-asset granularity, use `GET /b2b/earn/assets`. Depending on the reward asset and user-preferred currency, amounts in the response can be zero, eg. "0.00000000" BTC. It's the caller's responsibility to handle such cases, eg by showing amounts as "<0.000000001" or "~0". parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' - in: query name: currency deprecated: false description: The user-preferred currency. schema: nullable: false type: string maxLength: 16 style: form allowEmptyValue: false responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: auto_earn_eligible: description: Whether the user is eligible for Auto-Earn type: boolean auto_earn_enabled: description: >- Whether there is currently at least one Earn allocation active for the user type: boolean auto_earn_last_changed: nullable: true description: >- When the Auto-Earn feature has last been turned on or off. type: string format: date-time payout_period: example: PT15M description: Payout period of all Auto-Earn rewards. type: string total_allocated_converted: example: '1.23' description: >- Total allocated by the user. Denominated in requested `quote`. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 total_rewarded_converted_true_rates: example: '1.23' description: >- Total rewards accrued by the user, using "sum of individually converted amounts". This means "true" historic conversion rates at the times the payouts happened, are used. The resulting sum is also referred to as "never-decreasing amount". Also, see `total_rewarded_converted_current_rate`. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 total_rewarded_converted_current_rate: example: '1.23' description: >- Total rewards accrued by the user, using "converted total of native amounts". This means the current day conversion rate is used to convert the sum of native amounts. Unlike `total_rewarded_converted_true_rates`, this summing strategy can yield "decreasing amounts". If the native asset appreciates relative to the requested currency, the total reward in currency may decrease even though native rewards have increased. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 num_earning_assets: description: >- Number of active allocations, which under Auto-Earn is the same as number of earning assets. type: integer format: uint32 minimum: 0 upcoming_rewards: description: |- Upcoming rewards. Includes an entry for each earning asset. type: array items: description: >- Earn event. Currently, only events of type `Reward` are supported. properties: date: description: Date of the payout. type: string format: date-time asset: description: Asset of the payout. type: string maxLength: 16 accumulated_amount: description: >- Accumulated amount until now. Denominated in native and requested `currency`. type: object properties: native: example: '1.23' description: Amount in the native asset type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 converted: example: '1.23' description: >- Amount converted into the user-preferred currency type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - converted - native estimated_pending_amount: nullable: true description: >- Estimated pending amount from now until payout on payout `date`. Denominated in native and requested `currency`. Set to None if `date` is in the past, meaning `accumulated_amount` is the final reward amount and no pending amount is outstanding. type: object properties: native: example: '1.23' description: Amount in the native asset type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 converted: example: '1.23' description: >- Amount converted into the user-preferred currency type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - converted - native required: - accumulated_amount - asset - date required: - auto_earn_eligible - auto_earn_enabled - num_earning_assets - payout_period - total_allocated_converted - total_rewarded_converted_current_rate - total_rewarded_converted_true_rates - upcoming_rewards '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/earn/assets: get: operationId: listEmbedEarnAssets tags: - Earn summary: List Earn Assets description: > List Earn Assets. Filters: by asset/s, by user. Modifiers: user-preferred currency (quote). The user can optionally be passed in the request, which shows active asset allocations of the user in the response. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: assets deprecated: false description: >- Filter specific assets by asset name. Empty filter returns all assets. schema: default: [] type: array items: type: string maxLength: 16 style: form allowEmptyValue: false - in: query name: user deprecated: false description: | Filter assets by a specific user. Setting the user has two effects: 1. Active non-zero per-asset allocations of the user are included in the response 2. The list of returned assets is filtered by the user's country/eligibility. schema: nullable: true type: string minLength: 14 maxLength: 42 example: AA07 N84G DLNK DA3I style: form - in: query name: currency deprecated: false description: >- The user-preferred currency. This field is ignored if `user` is not set, and it must be set if `user` is set. schema: nullable: true type: string maxLength: 16 style: form allowEmptyValue: true responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: assets: description: All assets that can yield rewards. type: object additionalProperties: description: >- Earn Asset A single asset that can yield rewards. Field `apr_estimate` is expected to be always set, independent of a user's Auto-Earn status. Note: APR estimates may not be returned in edge cases where a user enables Auto-Earn in one country and then moves to another country where some auto-earning assets are unavailable. In such cases, the user may still auto-earn these assets but without APR estimates. To resolve this, users can disable and re-enable Auto-Earn, which will respect the country change by only enabling Auto-Earn for assets available in the new country. type: object properties: apr_estimate: type: object description: >- low and high estimate of the yield of this Earn asset. properties: low: $ref: '#/components/schemas/BigDecimal' description: >- Minimal expected yield percentage for one year high: $ref: '#/components/schemas/BigDecimal' description: >- Maximal expected yield percentage for one year required: - high - low user_allocation: nullable: true description: User allocation for this asset. type: object properties: total_rewarded: description: >- Total rewards accrued by the user (excl. fees). Holds native amount and amount denominated in user-preferred `currency`. type: object properties: native: $ref: '#/components/schemas/BigDecimal' description: Amount in the native asset converted: $ref: '#/components/schemas/BigDecimal' description: >- Amount converted into the user-preferred currency required: - converted - native total_allocated: description: >- Total allocated by the user. Holds native amount and amount denominated in user-preferred `currency`. type: object properties: native: $ref: '#/components/schemas/BigDecimal' description: Amount in the native asset converted: $ref: '#/components/schemas/BigDecimal' description: >- Amount converted into the user-preferred currency required: - converted - native upcoming_reward_date: $ref: '#/components/schemas/Date' description: Upcoming reward date. required: - assets '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/earn/{user}/auto: put: operationId: toggleEmbedAutoEarn summary: Toggle Auto-Earn tags: - Earn description: > Toggle Auto-Earn of a user. Toggling Auto-Earn is an async operation, which is triggered by calling this endpoint. Therefore, the response is empty. To fetch the users current Auto-Earn status, use `GET /b2b/earn/{user}`. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' description: User to toggle the Auto-Earn status for - in: query name: want_enabled description: Whether to enable or disable Auto-Earn required: true schema: type: boolean responses: '200': description: >- Successful response indicating the Auto-Earn toggle operation was triggered. The response body is empty on success. content: application/json: schema: type: object properties: result: nullable: true type: object '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/withdrawals/methods/{asset}: get: operationId: listEmbedWithdrawalMethods summary: List Withdrawal Methods tags: - Transfers description: | List available withdrawal methods for a given asset. Returns withdrawal methods with networks, estimated fees, and limits. Use `method_id` and (optionally) `fee_token` to prepare withdrawals. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 - $ref: '#/components/parameters/AssetPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: methods: type: array items: type: object properties: method_id: description: Stable identifier for the funding method type: string format: uuid network: nullable: true description: >- Network / method display name (e.g., "Bitcoin", "Ethereum") type: string network_info: nullable: true description: Blockchain network metadata type: object properties: explorer: description: Link to the blockchain explorer type: string confirmations: description: Number of confirmations required type: string est_confirmation_time: description: >- Estimated time to reach the required confirmations type: string contract_address: nullable: true description: >- Token contract address (for ERC-20 / wrapped tokens) type: string required: - explorer - confirmations - est_confirmation_time fee: nullable: true description: >- Estimated withdrawal fee, denominated in the requested asset. type: object properties: asset_class: description: Asset class default: currency type: string enum: - currency asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount fee_token: nullable: true description: >- Opaque fee token valid for 10 minutes. Submit in the withdrawal request to guarantee the quoted fee. type: string minimum: nullable: true description: >- Minimum withdrawal amount, denominated in the requested asset. type: object properties: asset_class: description: Asset class default: currency type: string enum: - currency asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount maximum: nullable: true description: >- Maximum withdrawal amount for this method, accounting for the per-transaction cap and remaining user limits. type: object properties: asset_class: description: Asset class default: currency type: string enum: - currency asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount required: - method_id required: - methods '400': description: > Bad Request. Error codes: - `ENexus:Unknown asset` — the specified asset is not recognized — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_asset: summary: Unknown asset value: errors: - status: '400' code: ENexus:Unknown asset detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/withdrawals/addresses/validate: post: operationId: validateEmbedWithdrawalAddress summary: Validate Withdrawal Address tags: - Transfers description: > Validate a crypto withdrawal address for the provided asset and method. This endpoint validates the address format and network compatibility but does not persist the address. parameters: - $ref: '#/components/parameters/PaywardVersion' requestBody: content: application/json: schema: type: object properties: asset: description: Asset to validate against (e.g., `BTC`, `ETH`) $ref: '#/components/schemas/AssetName' method_id: description: >- Withdrawal method identifier from `GET /b2b/funds/withdrawals/methods/{asset}` type: string format: uuid address: description: The crypto address to validate type: string memo: nullable: true description: Memo or tag for networks that require one (e.g., XRP, XLM) type: string required: - asset - method_id - address required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: valid: description: Whether the address is valid type: boolean required: - valid '400': description: > Bad Request. Error codes: - `EGeneral:Bad data` — invalid `method_id` or address format — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_method_id: summary: Invalid method_id value: errors: - status: '400' code: EGeneral:Bad data detail: Unknown or invalid method_id result: null invalid_address: summary: Invalid withdrawal address value: errors: - status: '400' code: EGeneral:Bad data detail: 'Invalid address: Invalid checksum' result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/withdrawals/addresses: get: operationId: listEmbedWithdrawalAddresses summary: List Withdrawal Addresses tags: - Transfers description: | List saved withdrawal addresses for the effective account. You can optionally filter by `asset`, `method_id`, and `key`. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 - in: query name: asset required: false schema: nullable: true description: Filter by asset (e.g., `BTC`, `ETH`) $ref: '#/components/schemas/AssetName' - in: query name: method_id required: false schema: nullable: true description: Filter by withdrawal method identifier type: string format: uuid - in: query name: key required: false schema: nullable: true description: Filter by saved withdrawal address key type: string responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: addresses: type: array items: type: object properties: key: description: User-provided name for this address type: string asset: description: Asset $ref: '#/components/schemas/AssetName' method_id: description: Withdrawal method identifier type: string format: uuid method_name: description: Withdrawal method display name type: string address: description: The crypto withdrawal address type: string memo: nullable: true description: Memo for networks that require it type: string tag: nullable: true description: Tag for networks that require it type: string created_at: nullable: true description: When the address was saved (ISO 8601) $ref: '#/components/schemas/DateTime' required: - key - asset - method_id - method_name - address required: - addresses '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' post: operationId: saveEmbedWithdrawalAddress summary: Save Withdrawal Address tags: - Transfers description: | Validate and save a withdrawal address for future withdrawals. Returns the address key that should be used when calling `POST /b2b/funds/withdrawals`. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 requestBody: content: application/json: schema: type: object properties: asset: description: Asset (e.g., `BTC`, `ETH`) $ref: '#/components/schemas/AssetName' method_id: description: >- Withdrawal method identifier from `GET /b2b/funds/withdrawals/methods/{asset}` type: string format: uuid key: description: User-provided name for this address type: string address: description: The crypto withdrawal address type: string memo: nullable: true description: Memo for networks that require it type: string tag: nullable: true description: Tag for networks that require it type: string required: - asset - method_id - key - address required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: key: description: The saved withdrawal key type: string tag: nullable: true description: Tag associated with the saved address (when present) type: string required: - key '400': description: > Bad Request. Error codes: - `EGeneral:Bad data` — invalid key, method_id, or address payload — not retryable - `ENexus:Unknown asset` — the specified asset is not recognized — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: bad_data: summary: Invalid address payload value: errors: - status: '400' code: EGeneral:Bad data detail: Unknown or invalid method_id result: null unknown_asset: summary: Unknown asset value: errors: - status: '400' code: ENexus:Unknown asset detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': description: > Conflict. Error codes: - `EFunding:Duplicate withdraw key` — the provided key already exists — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate_withdraw_key: summary: Duplicate withdrawal key value: errors: - status: '409' code: EFunding:Duplicate withdraw key detail: null result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/withdrawals/addresses/{key}: delete: operationId: deleteEmbedWithdrawalAddress summary: Delete Withdrawal Address tags: - Transfers description: > Delete a saved withdrawal address by key. Once deleted, the key cannot be used for new withdrawals until the address is saved again. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 - in: path name: key required: true schema: description: The saved address key to delete type: string responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true '400': description: > Bad Request. Error codes: - `EGeneral:Bad data` — invalid withdrawal key format — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_key: summary: Invalid withdrawal key value: errors: - status: '400' code: EGeneral:Bad data detail: Withdrawal address key is invalid result: null '401': $ref: '#/components/responses/UnauthorizedError' '404': description: > Not Found. Error codes: - `EFunding:Unknown withdraw key` — the provided key does not exist — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_withdraw_key: summary: Unknown withdrawal key value: errors: - status: '404' code: EFunding:Unknown withdraw key detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' patch: operationId: updateEmbedWithdrawalAddress summary: Update Withdrawal Address tags: - Transfers description: | Update a saved withdrawal address key. This endpoint renames an existing key; the withdrawal destination itself remains unchanged. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 - in: path name: key required: true schema: description: The saved address key to update type: string requestBody: content: application/json: schema: type: object properties: new_key: description: New saved address key type: string required: - new_key required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: key: description: The updated key type: string required: - key '400': description: | Bad Request. Error codes: - `EGeneral:Bad data` — invalid key format — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_key: summary: Invalid key format value: errors: - status: '400' code: EGeneral:Bad data detail: Withdrawal address key is invalid result: null '401': $ref: '#/components/responses/UnauthorizedError' '404': description: > Not Found. Error codes: - `EFunding:Unknown withdraw key` — the provided key does not exist — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_withdraw_key: summary: Unknown withdrawal key value: errors: - status: '404' code: EFunding:Unknown withdraw key detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '409': description: > Conflict. Error codes: - `EFunding:Duplicate withdraw key` — `new_key` already exists — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicate_withdraw_key: summary: Duplicate withdrawal key value: errors: - status: '409' code: EFunding:Duplicate withdraw key detail: null result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/withdrawals: post: operationId: withdrawEmbedFunds summary: Withdraw Funds tags: - Transfers description: | Withdraw funds from a master account or, when `user` is provided, from a sub-account on behalf of its owner. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: user required: false schema: nullable: true description: >- IIBAN of the target user. If omitted, applies to the master account. type: string minLength: 14 maxLength: 42 requestBody: content: application/json: schema: type: object properties: asset: description: Asset to withdraw $ref: '#/components/schemas/AssetName' key: description: Saved withdrawal address key type: string amount: description: Amount to withdraw $ref: '#/components/schemas/BigDecimal' fee_token: nullable: true description: >- Fee token from `GET /b2b/funds/withdrawals/methods`, guarantees the quoted fee for 10 minutes. type: string idempotency_token: description: >- Key used to guarantee idempotency. Reusing the same key on retry returns the original result. type: string format: uuid preview: description: >- When `true`, only returns quoted `amount`, `fee`, and `total`; no withdrawal is created. default: false type: boolean required: - asset - key - amount - idempotency_token required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: ref_id: description: >- Reference ID used to track the withdrawal status. Empty when `preview` is `true`. type: string amount: description: >- Amount that will be sent to the destination (after fees) $ref: '#/components/schemas/BigDecimal' fee: description: Network fee charged $ref: '#/components/schemas/BigDecimal' total: description: Total debited from the user balance (amount + fee) $ref: '#/components/schemas/BigDecimal' fee_token: nullable: true description: >- Fee token used to guarantee the quoted fee for 10 minutes. type: string required: - ref_id - amount - fee - total '400': description: > Bad Request. Error codes: - `EGeneral:Bad data` — invalid request payload (for example, non-positive amount) — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: bad_data: summary: Invalid withdrawal payload value: errors: - status: '400' code: EGeneral:Bad data detail: Expected positive amount result: null '401': $ref: '#/components/responses/UnauthorizedError' '404': description: > Not Found. Error codes: - `EFunding:Unknown withdraw key` — the provided withdrawal key does not exist — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_withdraw_key: summary: Unknown withdrawal key value: errors: - status: '404' code: EFunding:Unknown withdraw key detail: Unknown withdraw key result: null '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/transactions: get: operationId: listEmbedFundingTransactions summary: List Funding Transactions tags: - Transfers description: | List Funding transactions Funding transactions can be of type withdrawal or deposit. Currently, this is a master-only operation. Therefore, no User parameter exists. parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: type required: true deprecated: false description: Request funding transactions of the specified type schema: type: string enum: - withdrawal - deposit style: form allowEmptyValue: false - in: query name: cursor deprecated: false description: Pagination cursor for fetching the next set of results schema: nullable: true type: string style: form allowEmptyValue: true - in: query name: page_size deprecated: false description: >- Number of transactions to return per page. Default is 25 if not specified. schema: default: 25 type: integer format: uint32 minimum: 1 maximum: 500 style: form allowEmptyValue: false responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: transactions: description: List of funding transactions type: array items: type: object properties: type: description: Transaction type type: string enum: - withdrawal - deposit date: example: '2023-03-13T12:34:56Z' description: Transaction date type: string asset: description: Transaction asset type: string maxLength: 16 amount: example: '1.23' description: Transaction amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 status: description: Transaction status type: string enum: - initial - pending - settled - success - partial - failure ref_id: description: Reference ID type: string required: - amount - asset - date - ref_id - status - type next_cursor: nullable: true description: Cursor to use for fetching the next page of results type: string required: - transactions '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/deposits/methods/{asset}: get: operationId: listEmbedDepositMethods summary: List Deposit Methods tags: - Transfers description: | List available deposit methods for a given asset. Returns method details including fees, limits, and network information. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - $ref: '#/components/parameters/AssetPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: methods: type: array items: type: object properties: method_id: description: Stable UUID identifier for the deposit method type: string format: uuid network: nullable: true description: >- Network / method display name (e.g., "Bitcoin", "Ethereum") type: string network_info: nullable: true description: Blockchain network metadata type: object properties: explorer: description: Link to the blockchain explorer type: string confirmations: description: Number of confirmations required type: string est_confirmation_time: description: >- Estimated time to reach the required confirmations type: string contract_address: nullable: true description: >- Token contract address (for ERC-20 / wrapped tokens) type: string required: - explorer - confirmations - est_confirmation_time fee: nullable: true description: >- Deposit fee, denominated in the requested asset. Null if no fee applies. type: object properties: asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount minimum: nullable: true description: Minimum deposit amount type: object properties: asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount maximum: nullable: true description: >- Maximum deposit amount, accounting for periodic limits and per-transaction cap type: object properties: asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount address_setup_fee: nullable: true description: >- One-time fee charged to the first deposit on the generated address. Null if no fee applies. type: object properties: asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - asset - amount fee_percentage: nullable: true description: >- Percentage fee applied to deposits. Null if no fee applies. $ref: '#/components/schemas/BigDecimal' deposit_limit_meta: nullable: true description: >- Full periodic deposit limit breakdown by type and rolling window type: array items: type: object properties: limit_type: description: >- Type of limit (e.g., "Amount", "EquivAmount") type: string limits: description: >- Maximum and remaining limit for each rolling window (keyed by seconds) type: object additionalProperties: type: object properties: remaining: description: Remaining limit the user has $ref: '#/components/schemas/BigDecimal' maximum: description: Maximum limit the user is allowed $ref: '#/components/schemas/BigDecimal' required: - maximum - remaining required: - limit_type - limits required: - method_id - fee - fee_percentage - address_setup_fee - maximum - minimum required: - methods '400': description: > Bad Request. Error codes: - `ENexus:Unknown asset` — the specified asset is not recognized — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_asset: summary: Unknown asset value: errors: - status: '400' code: ENexus:Unknown asset detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/funds/deposits/addresses: get: operationId: listEmbedDepositAddresses summary: List Deposit Addresses tags: - Transfers description: | List deposit addresses for a given asset and method. Returns paginated results with address details including fees and limits. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: query name: asset required: true schema: description: The asset to list deposit addresses for (e.g., `BTC`, `ETH`) $ref: '#/components/schemas/AssetName' - in: query name: method_id required: true schema: description: >- The deposit method identifier (UUID from the list methods response) type: string format: uuid - in: query name: cursor schema: nullable: true description: Opaque pagination cursor from a previous response type: string responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: addresses: type: array items: type: object properties: asset: description: The asset this address is for $ref: '#/components/schemas/AssetName' method_id: description: The deposit method these addresses belong to type: string format: uuid address: nullable: true description: The crypto deposit address type: string tag: nullable: true description: >- Deposit tag for networks that require it (e.g., XRP) type: string memo: nullable: true description: >- Deposit memo for networks that require it (e.g., XLM) type: string expire_time: nullable: true description: Address expiration time type: string format: date-time required: - asset - method_id - expire_time - address - minimum - maximum next_cursor: nullable: true description: >- Opaque cursor for fetching the next page of results. Absent when there are no more pages. type: string required: - addresses '400': description: > Bad Request. Error codes: - `ENexus:Unknown asset` — the specified asset is not recognized — not retryable - `EGeneral:Bad data` — invalid method_id or pagination cursor — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_asset: summary: Unknown asset value: errors: - status: '400' code: ENexus:Unknown asset detail: null result: null bad_method_id: summary: Unknown or invalid method_id value: errors: - status: '400' code: EGeneral:Bad data detail: Unknown or invalid method_id result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' post: operationId: createEmbedDepositAddress summary: Create Deposit Address tags: - Transfers description: | Create a new deposit address for a given asset and method. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' requestBody: content: application/json: schema: type: object properties: method_id: description: >- The deposit method identifier (UUID from the list methods response) type: string format: uuid asset: description: >- The asset to create a deposit address for (e.g., `BTC`, `ETH`) $ref: '#/components/schemas/AssetName' required: - asset - method_id required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: address: description: The generated crypto deposit address type: string name: nullable: true description: Display name for the address type: string tag: nullable: true description: Deposit tag for networks that require it (e.g., XRP) type: string memo: nullable: true description: Deposit memo for networks that require it (e.g., XLM) type: string expire_time: nullable: true description: >- Address expiration time — if absent the address does not expire type: string format: date-time is_new: nullable: true description: Whether the address was newly created type: boolean required: - address '400': description: > Bad Request. Error codes: - `ENexus:Unknown asset` — the specified asset is not recognized — not retryable - `EGeneral:Bad data` — invalid method_id — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknown_asset: summary: Unknown asset value: errors: - status: '400' code: ENexus:Unknown asset detail: null result: null bad_method_id: summary: Unknown or invalid method_id value: errors: - status: '400' code: EGeneral:Bad data detail: Unknown or invalid method_id result: null '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '422': description: > Unprocessable Entity. Error codes: - `EFunding:Too many addresses` — address limit reached for this method — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: too_many_addresses: summary: Too many addresses value: errors: - status: '422' code: EFunding:Too many addresses detail: null result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/portfolio/{user}/summary: get: operationId: getEmbedPortfolioSummary summary: Get Portfolio Summary tags: - Portfolios description: | Get the portfolio summary for a user. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' - $ref: '#/components/parameters/Quote' - in: query name: include[current_day_pnl] description: Include the current day pnl schema: type: boolean default: false responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: timestamp: description: >- The timestamp of the most recent change in any index price. Reflects the freshness of pricing data used for valuation. type: string format: date-time currency: description: The currency in which all values are expressed. type: string maxLength: 16 portfolio_value: example: '1.23' description: The portfolio value, in the provided `quote` currency. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 withheld_value: example: '1.23' description: >- The total value of funds currently withheld across the platform. Includes assets reserved for open orders, earn bonding/unbonding, and pending withdrawals. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 open_orders: example: '1.23' description: >- The value of balances specifically held for open orders. Represents locked funds for pending trades or positions. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 available_balance: example: '1.23' description: >- The freely available balance for trading or withdrawal. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 lots_upnl: nullable: true example: '1.23' description: Unrealized lots PNL type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 cost_basis: nullable: true example: '1.23' description: >- The total cost basis of the portfolio, calculated as the sum of the cost bases of all individual assets type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 current_day_pnl: nullable: true description: >- If requested by `include[current_day_pnl]` then this will represent the PnL for the current day. Note: As yesterday's balance isn't always available it returns a `since` to indicate when the PnL was calculated from If there are any issues calculating this, it will be set to null type: object properties: since: description: The time from which the PnL is calculated from type: string format: date-time pnl: example: '1.23' description: The PnL from `since` until now type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - pnl - since required: - available_balance - currency - open_orders - portfolio_value - timestamp - withheld_value '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/portfolio/{user}/history: get: operationId: getEmbedPortfolioHistory summary: Get Portfolio History tags: - Portfolios description: > Gets a portfolio's historical balances and valuations over time. **Pagination:** A maximum of **365 data points** are returned per request. If the requested date range would produce more than 365 data points, the response is truncated and a `next_cursor` is returned. Pass this cursor in a subsequent request to retrieve the next page. Repeat until `next_cursor` is absent. Important notes: - If the start of the range of asset data points is null - then you didn't have a balance in the asset. - If it's zero - then you may have had the asset in the past, but the balance in zero - Balance for the last day shows up at UTC + 5h due to processing times. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' - in: query name: include[assets][] description: Include historical balances by asset schema: type: array items: $ref: '#/components/schemas/AssetName' - in: query name: include[total_balance] description: Include the overall historical balance totals schema: type: boolean default: false - in: query name: include[total_pnl] description: Include the overall historical pnl totals schema: type: boolean default: false - in: query name: start_date description: >- Start date of the fetching window. Only balances for dates that are after `start_date` will be returned. This is an optional parameter. If not present it will be equal to `end_date` - 365 days by default. Note: if the range between `start_date` and `end_date` produces more than 365 data points, the response will be paginated via `next_cursor`. schema: $ref: '#/components/schemas/Date' - in: query name: end_date description: >- End date of the fetching window. Only balances for dates that are before `end_date` will be returned. This is an optional parameter. If not present then current date will be used by default. schema: $ref: '#/components/schemas/Date' - in: query name: resolution description: > The resolution of returned data. Only 1 out of each `resolution` days will be returned. For example if `resolution` is set to 7 then only one day for each week will be returned. Default: 1, every day will be returned. schema: $ref: '#/components/schemas/Uint32' default: 1 - $ref: '#/components/parameters/Quote' - in: query name: cursor description: >- Optional cursor for pagination. Use the `next_cursor` value from a previous response to fetch the next page of data points. When provided, other parameters are ignored (they are encoded in the cursor). schema: type: string responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: start_date: $ref: '#/components/schemas/Date' description: >- Effective `start_date` of the fetching window. This is useful for the client when `start_date` wasn't specified in request. end_date: $ref: '#/components/schemas/Date' description: >- Effective `end_date` of the fetching window. This is useful for the client when `end_date` wasn't specified in request. next_cursor: description: >- Cursor to use for fetching the next page of results. This will be present if the requested date range produces more than 365 data points (the per-request limit) and there is more data available. Pass this value as the `cursor` query parameter in the next request. type: string currency: $ref: '#/components/schemas/AssetName' description: >- Asset in which the balances were denominated in. Assumed to be asset `USD` if missing. total_pnl: $ref: '#/components/schemas/BigDecimal' description: >- Sum of all daily `total_pnl` values in the `history`. This will be `None` if `include.total_pnl` was false or if there were no PnL values. Note: This does not include the current day total_pnl_pct: $ref: '#/components/schemas/BigDecimal' description: >- Overall profit and loss percentage change for data points in history. Calculated as (`total_pnl` / first `total_balance` in `history`) * 100. This will be `None` if `total_pnl` or the first `total_balance` is unavailable, or if the first `total_balance` is zero. Note: This does not include the current day history: description: >- Time series data containing portfolio values over time. A maximum of 365 data points is returned per request. If more data is available, `next_cursor` will be present — pass it as the `cursor` query parameter to retrieve the next page. type: array items: description: A data point in the portfolio time series type: object properties: date: $ref: '#/components/schemas/Date' description: Timestamp for this data point total_balance: $ref: '#/components/schemas/BigDecimal' description: >- Total portfolio value/balance at this timestamp (if requested) total_pnl: $ref: '#/components/schemas/BigDecimal' description: >- Total profit and loss at this timestamp (if requested) total_pnl_pct: $ref: '#/components/schemas/BigDecimal' description: >- Total profit and loss (PnL) percentage relative to the starting balance of the current day. Calculated as: ```text (total_pnl / (total_balance - total_pnl)) * 100 ``` - `total_pnl` is the accumulated profit or loss. - `total_balance` is the ending balance for the day. - The starting balance is derived as `total_balance - total_pnl`. This field is set only if both `total_pnl` and `total_balance` are available. assets: description: >- Per-asset balances at this timestamp (if requested) type: object additionalProperties: description: A single asset's balance type: object properties: balance: $ref: '#/components/schemas/BigDecimal' description: Balance amount for this asset required: - date required: - end_date - history - start_date '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/portfolio/{user}/details: get: operationId: listEmbedPortfolioDetails summary: List Portfolio Details tags: - Portfolios description: | Lists owned assets in a user's portfolio. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/Quote' - $ref: '#/components/parameters/UserPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: timestamp: description: The timestamp when this portfolio data was generated type: string format: date-time currency: description: >- The currency in which asset values are denominated (matches the requested quote asset) type: string maxLength: 16 assets: description: >- List of assets owned by the user with their detailed information type: array items: type: object properties: asset: description: >- Asset of interest. All values other than `_value` are in the asset. type: string maxLength: 16 class: nullable: true description: >- The class of the 'asset' field. Default value is `currency` if the field is not set. type: string enum: - currency cash_balance: example: '1.23' description: >- The balance of the asset available for the account. This amount might not all be available for trading, withdrawing, staking etc, as some of it might be locked in margin, pending orders, or in other wallets. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 index_price: example: '1.23' description: >- The price of the asset at the time of the last index update. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 cash_value: example: '1.23' description: >- The value of the `cash_balance` in the requested quote currency. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 held_orders_spot: example: '1.23' description: The amount of the asset held in spot orders. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 avail_trade: nullable: true example: '1.23' description: >- The amount of the asset available for trading. This value is the `cash_balance` after subtracting various holds applied to the account for this asset (e.g. open orders). type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 avail_trade_value: nullable: true example: '1.23' description: >- The value of the `avail_trade` in the requested quote currency. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 credit_line_used: nullable: true example: '1.23' description: >- The amount of credit currently used for the asset, if available. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 credit_line_available: nullable: true example: '1.23' description: Available credit for the asset, if any. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 lots_upnl: nullable: true example: '1.23' description: >- The Unrealized Profit and Loss for the current balance (i.e. the amount the user would make if they sold the current balance as the current market price) type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 avg_entry_price: nullable: true example: '1.23' description: >- The volume-weighted average price at which the current balance was acquired. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 cost_basis: nullable: true example: '1.23' description: >- The total value spent to acquire the current asset balance. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - cash_balance - cash_value - held_orders_spot - index_price required: - assets - currency - timestamp '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/portfolio/{user}/transactions: get: operationId: listEmbedPortfolioTransactions summary: List Portfolio Transactions tags: - Portfolios description: | Lists the users trades and transactions parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' - in: query name: cursor deprecated: false schema: nullable: true description: Pagination cursor for fetching the next set of results type: string style: form allowEmptyValue: true - in: query name: types deprecated: false schema: nullable: true description: Filter for transaction types type: array items: type: string enum: - simple_order - simple_order_failed - custom_order - custom_order_failed - earn_reward - deposit style: form allowEmptyValue: true - in: query name: page_size deprecated: false schema: nullable: true description: >- Number of transactions to return per page. Default is 25 if not specified. type: integer format: uint64 minimum: 0 maximum: 25 style: form allowEmptyValue: true - in: query name: assets deprecated: false schema: nullable: true description: Filter transactions by specific assets type: array items: type: string maxLength: 16 style: form allowEmptyValue: true - in: query name: from_time deprecated: false schema: nullable: true description: Filter transactions that occurred after this timestamp (exclusive) type: string format: date-time style: form allowEmptyValue: true - in: query name: until_time deprecated: false schema: nullable: true description: >- Filter transactions that occurred before or at this timestamp (inclusive) type: string format: date-time style: form allowEmptyValue: true - in: query name: statuses deprecated: false schema: nullable: true description: Filter transactions by their status type: array items: description: Filter criteria for transaction status in query results. type: string enum: - no_status - unspecified - in_progress - successful - failed style: form allowEmptyValue: true - in: query name: ids deprecated: false schema: nullable: true description: Filter transactions by specific transaction IDs type: array items: description: A unique identifier for a portfolio transaction. type: string style: form allowEmptyValue: true - in: query name: sorting deprecated: false schema: nullable: true description: Specify the order of results (ascending or descending by time) type: string enum: - descending - ascending style: form allowEmptyValue: true - in: query name: ref_ids deprecated: false schema: nullable: true description: Reference ID filters, this can be used to filter by quote id. type: array items: type: object properties: type: description: Type of `ref_id` type: string enum: - simple_order_quote - simple_order_quote_failed ref_id: description: Ref id itself type: string required: - ref_id - type style: form allowEmptyValue: true - in: query name: quote deprecated: false schema: nullable: true description: >- Currency to use for quoting amounts and fees in the response. Quoting is best-effort based on rates at transaction time. If not provided or if quoting is unavailable, quoted fields will be `None`. type: string maxLength: 16 style: form allowEmptyValue: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: transactions: description: >- List of trade transactions matching the query parameters type: array items: description: >- Comprehensive information about a user trade transaction. type: object properties: id: description: Unique identifier for the transaction type: string time: description: Timestamp when the transaction occurred type: string format: date-time type: description: The transaction type type: string enum: - simple_order - simple_order_failed - custom_order - custom_order_failed - earn_reward status: nullable: true description: Current status of the transaction, if available type: string enum: - unspecified - in_progress - successful - failed ref_id: description: Primary reference identifier type: string ref_id2: nullable: true description: >- Secondary reference identifier (typically quote ID), if available type: string spend: nullable: true description: >- Details about the asset spent in this transaction, if applicable type: object properties: ledger_id: nullable: true description: >- Associated ledger entry identifier, if available type: string time: nullable: true description: >- Timestamp of the funds movement, if available type: string format: date-time amount: description: >- Principal amount of the asset involved in the transaction type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_amount: nullable: true description: >- Principal amount converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset fee: nullable: true description: Fee charged for the transaction, if any type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_fee: nullable: true description: >- Fee converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset total: description: >- Total amount including fees (debit or credit) type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_total: nullable: true description: >- Total amount converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset balance: nullable: true description: >- Remaining balance after the transaction, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset required: - amount - total receive: nullable: true description: >- Details about the asset received in this transaction, if applicable type: object properties: ledger_id: nullable: true description: >- Associated ledger entry identifier, if available type: string time: nullable: true description: >- Timestamp of the funds movement, if available type: string format: date-time amount: description: >- Principal amount of the asset involved in the transaction type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_amount: nullable: true description: >- Principal amount converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset fee: nullable: true description: Fee charged for the transaction, if any type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_fee: nullable: true description: >- Fee converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset total: description: >- Total amount including fees (debit or credit) type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quoted_total: nullable: true description: >- Total amount converted to the requested quote currency, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset balance: nullable: true description: >- Remaining balance after the transaction, if available type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 asset_name: nullable: true description: >- Human-readable name of the asset (e.g., "Bitcoin" for BTC) type: string amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset required: - amount - total details: nullable: true description: Transaction details / data oneOf: - description: >- Details for SO like transactions ex: '`SimpleOrder`' type: object properties: type: type: string enum: - simple_order quote_id: description: Simple order quote id type: string trade_type: description: >- What type the trade is from the user's perspective (no actual trades here) type: string enum: - unspecified - buy - sell - convert parent_transaction: nullable: true description: Parent transaction id type: string required: - quote_id - trade_type - type - description: >- Details for CO like transactions ex: '`CustomOrder`' type: object properties: type: type: string enum: - custom_order trade_type: description: >- What type the trade is from the user's perspective (no actual trades here) type: string enum: - unspecified - buy - sell - convert parent_transaction: nullable: true type: string required: - trade_type - type - description: >- Details for SO-failure like transactions ex: '`SimpleOrderFailed`' type: object properties: type: type: string enum: - simple_order_failed receive_asset: description: Receive asset type: object properties: asset: description: Asset name in one set naming scheme type: string class: description: Asset class of the asset type: string enum: - currency required: - asset - class spend_asset: description: Spend asset type: object properties: asset: description: Asset name in one set naming scheme type: string class: description: Asset class of the asset type: string enum: - currency required: - asset - class trade_type: description: >- What type the trade is from the user's perspective (no actual trades here) type: string enum: - unspecified - buy - sell - convert failure_reason: description: Failure reason type: string enum: - other - insufficient_funds - card_issue - user_account_issue required: - failure_reason - receive_asset - spend_asset - trade_type - type - description: >- Details for CO-failure like transactions ex: '`CustomOrderFailed`' type: object properties: type: type: string enum: - custom_order_failed receive_asset: description: Receive asset type: object properties: asset: description: Asset name in one set naming scheme type: string class: description: Asset class of the asset type: string enum: - currency required: - asset - class spend_asset: description: Spend asset type: object properties: asset: description: Asset name in one set naming scheme type: string class: description: Asset class of the asset type: string enum: - currency required: - asset - class trade_type: description: >- What type the trade is from the user's perspective (no actual trades here) type: string enum: - unspecified - buy - sell - convert failure_reason: description: Failure reason type: string enum: - other - insufficient_funds - card_issue - user_account_issue required: - failure_reason - receive_asset - spend_asset - trade_type - type - description: Details for Earn reward type: object properties: type: type: string enum: - earn_reward required: - type required: - id - ref_id - time - type next_cursor: nullable: true description: Next cursor type: string required: - transactions '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/quotes: post: operationId: requestEmbedQuote summary: Request Quote tags: - Quotes description: | Request a price quote for an asset, that may be used to execute a trade later on. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' requestBody: content: application/json: schema: type: object properties: type: description: >- Type of quote (receive or spend). - `receive`: Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC - `spend`: Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: > Asset and amount that the user wants to specify exactly - For `receive` quote_type: This is the exact amount the user wants to receive - For `spend` quote_type: This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: $ref: '#/components/schemas/AssetName' amount: $ref: '#/components/schemas/BigDecimal' required: - amount - asset quote: description: > The other asset involved in the transaction - For `receive` quote_type: This is the asset the user will spend (in a variable amount) - For `spend` quote_type: This is the asset the user will receive (in a variable amount) type: object properties: asset: $ref: '#/components/schemas/AssetName' description: Name of the asset to receive required: - asset fee_bps: $ref: '#/components/schemas/BasisPoints' description: | Custom fee amount expressed in basis points (1 bps = 0.01%) spread_bps: $ref: '#/components/schemas/BasisPoints' description: > Custom spread amount expressed in basis points (1 bps = 0.01%) quote_currency: $ref: '#/components/schemas/AssetName' description: > If set will return `quoted_spend`, `quoted_receive`, `quoted_unit_price` required: - amount - fee_bps - quote - spread_bps - type required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: type: object properties: quote_id: description: Unique identifier for the quote type: string type: description: Type of quote (buy or sell) type: string enum: - receive - spend status: description: Current status of the quote oneOf: - type: string enum: - new - accepted - quote_cancelled - order_complete - credit_transfer_complete - quote_execution_failed - description: Unknown failure type: object properties: unknown: type: string required: - unknown expires: description: Timestamp when the quote expires is ISO 8601 format type: string format: date-time spend: description: Details about the asset being spent type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_spend: nullable: true description: >- Details about the asset being spent, denoted in `quoted_currency` asset Is null is `quote_currency` is null type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total receive: description: Details about the asset being received type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_receive: nullable: true description: >- Details about the asset being received, denoted in `quote_currency` asset Is null is `quote_currency` is null type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total unit_price: description: Price information for the transaction type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price quoted_unit_price: nullable: true description: >- Price information for the transaction, denoted in `quote_currency` asset Is null is `quote_currency` is null type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price required: - expires - quote_id - receive - spend - status - type - unit_price '400': description: | Bad Request. Error codes: - `EAPI:Quantity is too small for asset` — not retryable - `EAPI:Quantity is too large for asset` — not retryable - `ENexus:Unknown quote asset` — not retryable - `ENexus:Asset disabled` — not retryable - `ENexus:Unknown amount asset` — not retryable - `EAPI:InvalidParameter` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quantity_too_small: summary: Quantity is too small for asset value: errors: - status: '400' code: EAPI:Quantity is too small for asset detail: null result: null asset_disabled: summary: Asset is disabled for trading value: errors: - status: '400' code: ENexus:Asset disabled detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '403': description: | Forbidden. Error codes: - `EAPI:User Locked` — not retryable (terminal) - `EPTL:UserKycDenyTrading` — not retryable (terminal) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: user_locked: summary: User account is locked (terminal) value: errors: - status: '403' code: EAPI:User Locked detail: null result: null kyc_deny: summary: User denied trading due to KYC (terminal) value: errors: - status: '403' code: EPTL:UserKycDenyTrading detail: null result: null '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': description: | Conflict. Error codes: - `EPTL:Not enough depth on book` — retryable (market conditions) - `EAPI:Potential wash trade` — not retryable (terminal) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_enough_depth: summary: Not enough depth on book (retryable) value: errors: - status: '409' code: EPTL:Not enough depth on book detail: null result: null wash_trade: summary: Potential wash trade (terminal) value: errors: - status: '409' code: EAPI:Potential wash trade detail: null result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/quotes/assets: get: operationId: listEmbedTradableAssets summary: List Tradable Assets tags: - Quotes description: > Retrieve the list of tradable assets available for a specific user. This endpoint returns asset information including trading status, decimal precision, and any restrictions on trading pairs. Use this to determine which assets a user can trade or include in quote requests. ## Filtering by Tradable Status The `tradable` query parameter controls which assets are returned based on their trading status: | Value | Behavior | |-------|----------| | `true` | Only returns assets with `tradable` status | | `false` | Only returns assets with `disabled` or `soon` status | | *(omitted)* | Returns all assets regardless of status | ## Asset Status Values | Status | Description | |--------|-------------| | `tradable` | Asset is available for trading | | `disabled` | Asset is currently disabled and cannot be traded | | `soon` | Asset will be available for trading soon | ## Disabled Against The `disabled_against` field lists assets that cannot be traded against this asset. For example, if `BTC` has `disabled_against: ["AED", "YB"]`, then BTC cannot be quoted against AED or YB. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: query name: tradable required: false description: > Filter assets by tradable status. When `true`, only tradable assets are returned. When `false`, only non-tradable assets (disabled or soon) are returned. When omitted, all assets are returned regardless of status. schema: type: boolean nullable: true responses: '200': description: Assets retrieved successfully content: application/json: schema: type: object properties: result: type: object properties: assets: type: array description: List of tradable assets available for the user items: type: object properties: name: type: string maxLength: 16 description: The asset ticker symbol example: BTC status: type: string description: Current trading status of the asset enum: - tradable - disabled - soon example: tradable disabled_against: type: array description: > List of assets that this asset cannot be traded against. Empty array means no restrictions. items: type: string example: - AED - YB decimals: type: integer format: uint32 minimum: 0 description: Number of decimal places for the asset example: 8 required: - name - status - disabled_against - decimals required: - assets '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/quotes/{quote_id}: get: operationId: getEmbedQuote summary: Get Quote tags: - Quotes description: | Gets the status of a quote that was previously requested. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - $ref: '#/components/parameters/QuoteIdPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: quote_id: description: Unique identifier for the quote type: string transaction_id: nullable: true description: Optional transaction ID if the quote has been executed type: string type: description: Type of quote (buy or sell) type: string enum: - receive - spend status: description: Current status of the quote oneOf: - type: string enum: - new - accepted - quote_cancelled - order_complete - credit_transfer_complete - quote_execution_failed - description: Unknown failure type: object properties: unknown: type: string required: - unknown expires: description: Timestamp when the quote expires is ISO 8601 format type: string format: date-time spend: description: Details about the asset being spent type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_spend: nullable: true description: >- Details about the asset being spent, denoted in `quoted_currency` asset Is null is `quote_currency` was null on the quote request type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_receive: nullable: true description: >- Details about the asset being received, denoted in `quote_currency` asset Is null is `quote_currency` was null on the quote request type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total receive: description: Details about the asset being received type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total unit_price: description: Price information for the transaction type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price quoted_unit_price: nullable: true description: >- Price information for the transaction, denoted in `quote_currency` asset Is null is `quote_currency` was null on the quote request type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price required: - expires - quote_id - receive - spend - status - type - unit_price '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': description: | Not Found. Error codes: - `ENexus:Quote not found` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '404' code: ENexus:Quote not found detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' put: operationId: executeEmbedQuote summary: Execute Quote tags: - Quotes description: | Executes a quote that was previously requested. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - $ref: '#/components/parameters/QuoteIdPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: quote_id: description: Unique identifier for the quote type: string status: description: Current status of the quote oneOf: - type: string enum: - new - accepted - quote_cancelled - order_complete - credit_transfer_complete - quote_execution_failed - description: Unknown failure type: object properties: unknown: type: string required: - unknown transaction_id: nullable: true description: >- Optional transaction ID if the quote was immediately executed. type: string required: - quote_id - status '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': description: > Conflict. Error codes: - `EPTL:Quote already accepted` — not retryable (terminal) - `EPTL:Quote cancelled` — not retryable (terminal) - `EPTL:Price quote expired` — not retryable (terminal) - `EPTL:Quote execution failed` — not retryable (terminal) - `EPTL:Insufficient funds for transfer` — not retryable (terminal), detail is dynamic content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quote_expired: summary: Price quote has expired (terminal) value: errors: - status: '409' code: EPTL:Price quote expired detail: null result: null insufficient_funds: summary: Insufficient funds for transfer (terminal) value: errors: - status: '409' code: EPTL:Insufficient funds for transfer detail: 'Available balance: 50.00 USD, required: 100.00 USD' result: null quote_execution_failed: summary: Quote execution failed (terminal) value: errors: - status: '409' code: EPTL:Quote execution failed detail: null result: null '422': description: | Unprocessable Entity. Error codes: - `EPTL:PTL unable to fund transfer for quote` — not retryable - `EPTL:PTL unable to fund order for quote` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unable_to_fund_transfer: summary: Unable to fund transfer for quote value: errors: - status: '422' code: EPTL:PTL unable to fund transfer for quote detail: null result: null unable_to_fund_order: summary: Unable to fund order for quote value: errors: - status: '422' code: EPTL:PTL unable to fund order for quote detail: null result: null '429': description: > Too Many Requests. Error codes: - `EPTL:User has too many quote executions in progress` — retryable (backoff) - `EPTL:User has reached volume threshold` — not retryable (terminal) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: too_many_executions: summary: Too many quote executions in progress (retryable) value: errors: - status: '429' code: EPTL:User has too many quote executions in progress detail: null result: null volume_threshold: summary: Volume threshold reached (terminal) value: errors: - status: '429' code: EPTL:User has reached volume threshold detail: null result: null '500': $ref: '#/components/responses/InternalError' '503': description: | Service Unavailable. Error codes: - `EPTL:Order cancelled. Try again.` — retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '503' code: EPTL:Order cancelled. Try again. detail: null result: null /b2b/quotes/limits: get: operationId: getEmbedQuoteLimits summary: Get Quote Limits tags: - Quotes description: > Request minimum, maximum and precision for trade using a given asset pair parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: query name: base_asset required: true schema: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type: This is the exact amount the user wants to receive - For `spend` quote_type: This is the exact amount the user wants to spend type: string maxLength: 16 style: form - in: query name: quote_asset required: true schema: description: >- The other asset involved in the transaction - For `receive` quote_type: This is the asset the user will spend (in a variable amount) - For `spend` quote_type: This is the asset the user will receive (in a variable amount) type: string maxLength: 16 style: form - in: query name: type required: true schema: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend style: form - in: query name: quote_currency required: false schema: nullable: true description: >- If set will return `quoted_spend`, `quoted_receive`, `quoted_unit_price` type: string maxLength: 16 style: form allowEmptyValue: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true description: Response including quote limits for a given asset pair type: object properties: asset: type: string minimum: description: absolute minimum amount type: string example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 maximum: description: absolute maximum amount type: string example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 precision: description: precision for amounts type: integer format: uint64 minimum: 0 minimum_tradable_amount: nullable: true description: minimum tradable amount type: string minimum_in_display: nullable: true type: object properties: asset: type: string amount: description: The amount type: string example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - amount maximum_in_display: nullable: true type: object properties: asset: type: string amount: description: The amount type: string example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - amount minimum_tradable_amount_in_display: nullable: true type: object properties: asset: type: string amount: description: The amount type: string example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - amount required: - asset - minimum - maximum - precision '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' /b2b/quotes/prospective: post: operationId: requestEmbedProspectiveQuote summary: Request Prospective Quote tags: - Quotes description: > Request a prospective quote for an asset pair, to receive an indicative price and fee. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' requestBody: content: application/json: schema: type: object properties: action: type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type: This is the exact amount the user wants to receive - For `spend` quote_type: This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type: This is the asset the user will spend (in a variable amount) - For `spend` quote_type: This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type trigger: nullable: true description: >- If set will return the fee of the quote executed at the specified price target anyOf: - type: object properties: type: type: string enum: - price base_asset: description: The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type quote_currency: nullable: true description: >- If set will return `quoted_spend`, `quoted_receive`, `quoted_unit_price` type: string maxLength: 16 required: - action required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: type: description: Type of quote (buy or sell) type: string enum: - receive - spend spend: description: Details about the asset being spent type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total receive: description: Details about the asset being received type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total unit_price: description: Price information for the transaction type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price quoted_spend: nullable: true description: >- Details about the asset being spent, denoted in `quoted_currency` asset Is null if `quote_currency` is null type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_receive: nullable: true description: >- Details about the asset being received, denoted in `quote_currency` asset Is null if `quote_currency` is null type: object properties: asset: description: Name of the asset type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency total: example: '1.23' description: Total amount including fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 fee: example: '1.23' description: Transaction fee amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 subtotal: example: '1.23' description: Amount excluding fees type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - asset - fee - subtotal - total quoted_unit_price: nullable: true description: >- Price information for the transaction, denoted in `quote_currency` asset Is null if `quote_currency` is null type: object properties: asset: description: The asset the unit price is for type: string maxLength: 16 asset_class: nullable: true description: Class of the asset type: string enum: - currency unit_price: example: '1.23' description: The unit price type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 denomination_asset: description: What the unit price is denominated in type: string maxLength: 16 denomination_asset_class: nullable: true description: Class of the denomination asset type: string enum: - currency required: - asset - denomination_asset - unit_price required: - receive - spend - type - unit_price '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/custom-orders: post: operationId: createEmbedCustomOrder summary: Create Custom Order tags: - Custom Orders description: | Submit a custom order with a specified trigger condition. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' requestBody: content: application/json: schema: type: object properties: trigger: anyOf: - type: object properties: type: type: string enum: - price base_asset: description: The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type action: type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type This is the exact amount the user wants to receive - For `spend` quote_type This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type This is the asset the user will spend (in a variable amount) - For `spend` quote_type This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type name: type: string required: - action - name - trigger required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: order: type: object properties: id: description: Unique identifier for the custom order. type: string name: description: Action display name (set by the user). type: string action: description: Trade action. type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type This is the exact amount the user wants to receive - For `spend` quote_type This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type This is the asset the user will spend (in a variable amount) - For `spend` quote_type This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type trigger: description: >- Trigger for the action trigger, for example time-based scheduled events. anyOf: - type: object properties: type: type: string enum: - price base_asset: description: >- The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: >- The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type created_at: description: Action creation timestamp type: string format: date-time updated_at: description: Action most recent update timestamp type: string format: date-time status: description: >- Signals if the action is currently active or not, One of 'active', 'completed' 'cancelled' or 'paused' oneOf: - description: Active action can be paused or cancelled. type: object properties: status: type: string enum: - active required: - status - description: Completed action can't change its status type: object properties: status: type: string enum: - completed required: - status - description: Cancelled action can't change its status type: object properties: status: type: string enum: - cancelled reason: oneOf: - type: string enum: - user_request - user_locked - expired_payment_method - asset_unavailable - pair_unavailable - retries_exhausted - funding_method_deleted - user_bundle_dissolved - user_bundle_liquidated - no_balances_to_rebalance_bundle - type: object properties: other: type: object properties: details: type: string required: - details required: - other required: - reason - status - description: >- Action occurrences won't be issued when the trigger event actually occurs. Paused action can be re-activated or cancelled. type: object properties: status: type: string enum: - paused reason: oneOf: - description: >- When multiple occurrences fail in a row due to problems with payment (e.g. insufficient balance fund) we pause the `ScheduledAction`. type: object properties: reason: type: string enum: - missed_payment required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too large amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_large required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too small amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_small required: - reason - description: User requested to pause the action type: object properties: reason: type: string enum: - user_request required: - reason - type: object properties: reason: type: string enum: - user_locked required: - reason - description: For example, expired card type: object properties: reason: type: string enum: - payment_method_issue required: - reason - description: >- User has insufficient margin to perform a given trade type: object properties: reason: type: string enum: - insufficient_margin required: - reason - description: The pair is currently not tradeable type: object properties: reason: type: string enum: - pair_unavailable required: - reason - description: >- The associated funding method got deleted type: object properties: reason: type: string enum: - funding_method_deleted required: - reason - description: >- Canadian Acquisition Limit (CAL) exceeded type: object properties: reason: type: string enum: - canadian_acquisition_limit_exceeded required: - reason - description: >- Canadian Suitability Limit (CAD SL) exceeded type: object properties: reason: type: string enum: - canadian_suitability_limit_exceeded required: - reason - description: >- There are restrictions on the user account that can be lifted over time without action on his side. E.g. the user may have been marked a potential fraudster on our side. type: object properties: reason: type: string enum: - user_temporarily_restricted required: - reason - description: >- Also used for deserializing unknown values, in which case the string representation of tha value is appended to the `details`. type: object properties: reason: type: string enum: - other details: type: string required: - details - reason - description: The user's bank account is not supported type: object properties: reason: type: string enum: - bank_account_not_supported required: - reason - description: >- The user's payment method needs to be reauthorized type: object properties: reason: type: string enum: - reauthorization_required required: - reason required: - reason - status required: - action - created_at - id - name - status - trigger - updated_at required: - order '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '422': description: >- Unprocessable Entity — the request was well-formed but could not be completed due to business constraints. Not retryable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '422' code: ECTS-Scheduler:Scheduled action validation error detail: The custom order would trigger immediately result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' get: operationId: listEmbedCustomOrders summary: List Custom Orders tags: - Custom Orders description: | Get a list of custom orders that were previously submitted. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: query name: statuses description: >- Filters the returned custom orders by one or more statuses. If omitted, all statuses are included. schema: type: array items: type: string enum: - active - cancelled - completed default: [] style: form explode: true allowEmptyValue: true - in: query name: cursor deprecated: false schema: nullable: true description: Pagination cursor for fetching the next set of results type: string style: form allowEmptyValue: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: orders: type: array items: type: object properties: id: description: Unique identifier for the custom order. type: string name: description: Action display name (set by the user). type: string action: description: Trade action. type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type: This is the exact amount the user wants to receive - For `spend` quote_type: This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type: This is the asset the user will spend (in a variable amount) - For `spend` quote_type: This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type trigger: description: >- Trigger for the action trigger, for example time-based scheduled events. anyOf: - type: object properties: type: type: string enum: - price base_asset: description: >- The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: >- The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type created_at: description: Action creation timestamp type: string format: date-time updated_at: description: Action most recent update timestamp type: string format: date-time status: description: >- Signals if the action is currently active or not, One of 'active', 'completed' 'cancelled' oneOf: - description: Active action can be cancelled. type: object properties: status: type: string enum: - active required: - status - description: Completed action can't change its status type: object properties: status: type: string enum: - completed required: - status - description: Cancelled action can't change its status type: object properties: status: type: string enum: - cancelled reason: oneOf: - type: string enum: - user_request - user_locked - expired_payment_method - asset_unavailable - pair_unavailable - retries_exhausted - funding_method_deleted - user_bundle_dissolved - user_bundle_liquidated - no_balances_to_rebalance_bundle - type: object properties: other: type: object properties: details: type: string required: - details required: - other required: - reason - status required: - action - created_at - id - name - status - trigger - updated_at next_cursor: nullable: true type: string required: - orders '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/custom-orders/{order_id}: get: operationId: getEmbedCustomOrder summary: Get Custom Order tags: - Custom Orders description: | Get a single custom order by ID. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: path name: order_id required: true schema: description: The ID of the custom order to retrieve type: string style: simple responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: order: type: object properties: id: description: Unique identifier for the custom order. type: string name: description: Action display name (set by the user). type: string action: description: Trade action. type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type: This is the exact amount the user wants to receive - For `spend` quote_type: This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type: This is the asset the user will spend (in a variable amount) - For `spend` quote_type: This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type trigger: description: >- Trigger for the action trigger, for example time-based scheduled events. anyOf: - type: object properties: type: type: string enum: - price base_asset: description: >- The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: >- The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type created_at: description: Action creation timestamp type: string format: date-time updated_at: description: Action most recent update timestamp type: string format: date-time status: description: >- Signals if the action is currently active or not, One of 'active', 'completed' 'cancelled' or 'paused' oneOf: - description: Active action can be paused or cancelled. type: object properties: status: type: string enum: - active required: - status - description: Completed action can't change its status type: object properties: status: type: string enum: - completed required: - status - description: Cancelled action can't change its status type: object properties: status: type: string enum: - cancelled reason: oneOf: - type: string enum: - user_request - user_locked - expired_payment_method - asset_unavailable - pair_unavailable - retries_exhausted - funding_method_deleted - user_bundle_dissolved - user_bundle_liquidated - no_balances_to_rebalance_bundle - type: object properties: other: type: object properties: details: type: string required: - details required: - other required: - reason - status - description: >- Action occurrences won't be issued when the trigger event actually occurs. Paused action can be re-activated or cancelled. type: object properties: status: type: string enum: - paused reason: oneOf: - description: >- When multiple occurrences fail in a row due to problems with payment (e.g. insufficient balance fund) we pause the `ScheduledAction`. type: object properties: reason: type: string enum: - missed_payment required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too large amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_large required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too small amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_small required: - reason - description: User requested to pause the action type: object properties: reason: type: string enum: - user_request required: - reason - type: object properties: reason: type: string enum: - user_locked required: - reason - description: For example, expired card type: object properties: reason: type: string enum: - payment_method_issue required: - reason - description: >- User has insufficient margin to perform a given trade type: object properties: reason: type: string enum: - insufficient_margin required: - reason - description: The pair is currently not tradeable type: object properties: reason: type: string enum: - pair_unavailable required: - reason - description: >- The associated funding method got deleted type: object properties: reason: type: string enum: - funding_method_deleted required: - reason - description: >- Canadian Acquisition Limit (CAL) exceeded type: object properties: reason: type: string enum: - canadian_acquisition_limit_exceeded required: - reason - description: >- Canadian Suitability Limit (CAD SL) exceeded type: object properties: reason: type: string enum: - canadian_suitability_limit_exceeded required: - reason - description: >- There are restrictions on the user account that can be lifted over time without action on his side. E.g. the user may have been marked a potential fraudster on our side. type: object properties: reason: type: string enum: - user_temporarily_restricted required: - reason - description: >- Also used for deserializing unknown values, in which case the string representation of tha value is appended to the `details`. type: object properties: reason: type: string enum: - other details: type: string required: - details - reason - description: The user's bank account is not supported type: object properties: reason: type: string enum: - bank_account_not_supported required: - reason - description: >- The user's payment method needs to be reauthorized type: object properties: reason: type: string enum: - reauthorization_required required: - reason required: - reason - status required: - action - created_at - id - name - status - trigger - updated_at required: - order '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/custom-orders/{order_id}/history: get: operationId: getEmbedCustomOrderHistory summary: Get Custom Order History tags: - Custom Orders description: | Get execution history for a single custom order. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: path name: order_id required: true schema: description: The ID of the custom order to retrieve history for type: string style: simple responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: history: type: array items: description: A single execution occurrence of a custom order. properties: id: description: Unique occurrence ID. type: string executed_action: nullable: true description: >- Details of the executed action, if a trade was initiated. type: object properties: quote_id: description: PTL quote ID associated with this execution. type: string required: - quote_id trigger: description: What triggered this occurrence. oneOf: - description: Triggered by a time condition. type: object properties: type: type: string enum: - time required: - type - description: Triggered by a price condition. type: object properties: type: type: string enum: - price required: - type - description: Triggered by a crypto deposit. type: object properties: type: type: string enum: - crypto_deposit required: - type - description: Triggered when a market opens. type: object properties: type: type: string enum: - market_open required: - type created_at: description: Occurrence creation timestamp. type: string format: date-time updated_at: description: Occurrence last update timestamp. type: string format: date-time required: - created_at - id - trigger - updated_at oneOf: - description: Occurrence completed successfully. type: object properties: status: type: string enum: - success required: - status - description: Occurrence failed. type: object properties: status: type: string enum: - failure failure_reason: description: Machine-readable failure code. type: string required: - failure_reason - status - description: Occurrence was skipped. type: object properties: status: type: string enum: - skipped skip_reason: description: Machine-readable skip reason. type: string required: - skip_reason - status - description: Occurrence is in progress. type: object properties: status: type: string enum: - in_progress stage: description: Current stage of execution. type: string required: - stage - status - description: >- Occurrence is pending (awaiting trigger condition). type: object properties: status: type: string enum: - pending required: - status required: - history '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/custom-orders/{id}/cancel: post: operationId: cancelEmbedCustomOrder summary: Cancel Custom Order tags: - Custom Orders description: > Cancels a custom order that was previously submitted but not yet completed. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserQuery' - in: path name: id required: true schema: description: Unique identifier for the quote type: string style: simple responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: order: type: object properties: id: description: Unique identifier for the custom order. type: string name: description: Action display name (set by the user). type: string action: description: Trade action. type: object properties: type: description: >- Type of quote (receive or spend) When `receive`: - Represents a 'fixed receive' scenario where the user specifies how much they want to receive in the `amount` field - Example: User wants to receive 100 USD by selling some amount of BTC When `spend`: - Represents a 'fixed spend' scenario where the user specifies how much they want to spend in the `amount` field to receive some amount of the `quote` asset - Example: User wants to spend 100 USD to buy some amount of BTC type: string enum: - receive - spend amount: description: >- Asset and amount that the user wants to specify exactly - For `receive` quote_type This is the exact amount the user wants to receive - For `spend` quote_type This is the exact amount the user wants to spend type: object properties: asset_class: default: currency type: string enum: - currency asset: type: string maxLength: 16 amount: example: '1.23' description: The amount type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 required: - amount - asset quote: description: >- The other asset involved in the transaction - For `receive` quote_type This is the asset the user will spend (in a variable amount) - For `spend` quote_type This is the asset the user will receive (in a variable amount) type: object properties: asset: description: Name of the asset to receive type: string maxLength: 16 required: - asset fee_bps: description: >- Custom fee amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ spread_bps: description: >- Custom spread amount expressed in basis points (1 bps = 0.01%) type: string pattern: ^\d{1,5}$ required: - amount - fee_bps - quote - spread_bps - type trigger: description: >- Trigger for the action trigger, for example time-based scheduled events. anyOf: - type: object properties: type: type: string enum: - price base_asset: description: >- The base asset of the pair to check the price in. type: string maxLength: 16 quote_asset: description: >- The quote asset of the pair to check the price in. type: string maxLength: 16 target_price: example: '1.23' description: >- The price denominated in the `base_asset`/`quote_asset` rate type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 condition: description: >- The condition associated with the target price. Greater than or equal to (gte) or less than or equal to (lte). type: string enum: - gte - lte required: - base_asset - condition - quote_asset - target_price - type created_at: description: Action creation timestamp type: string format: date-time updated_at: description: Action most recent update timestamp type: string format: date-time status: description: >- Signals if the action is currently active or not, One of 'active', 'completed' 'cancelled' or 'paused' oneOf: - description: Active action can be paused or cancelled. type: object properties: status: type: string enum: - active required: - status - description: Completed action can't change its status type: object properties: status: type: string enum: - completed required: - status - description: Cancelled action can't change its status type: object properties: status: type: string enum: - cancelled reason: oneOf: - type: string enum: - user_request - user_locked - expired_payment_method - asset_unavailable - pair_unavailable - retries_exhausted - funding_method_deleted - user_bundle_dissolved - user_bundle_liquidated - no_balances_to_rebalance_bundle - type: object properties: other: type: object properties: details: type: string required: - details required: - other required: - reason - status - description: >- Action occurrences won't be issued when the trigger event actually occurs. Paused action can be re-activated or cancelled. type: object properties: status: type: string enum: - paused reason: oneOf: - description: >- When multiple occurrences fail in a row due to problems with payment (e.g. insufficient balance fund) we pause the `ScheduledAction`. type: object properties: reason: type: string enum: - missed_payment required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too large amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_large required: - reason - description: >- We don't pause `ScheduledAction`s upon trading too small amounts, but used to in the past and keep this entry to be able to display those actions correctly. type: object properties: reason: type: string enum: - quantity_too_small required: - reason - description: User requested to pause the action type: object properties: reason: type: string enum: - user_request required: - reason - type: object properties: reason: type: string enum: - user_locked required: - reason - description: For example, expired card type: object properties: reason: type: string enum: - payment_method_issue required: - reason - description: >- User has insufficient margin to perform a given trade type: object properties: reason: type: string enum: - insufficient_margin required: - reason - description: The pair is currently not tradeable type: object properties: reason: type: string enum: - pair_unavailable required: - reason - description: >- The associated funding method got deleted type: object properties: reason: type: string enum: - funding_method_deleted required: - reason - description: >- Canadian Acquisition Limit (CAL) exceeded type: object properties: reason: type: string enum: - canadian_acquisition_limit_exceeded required: - reason - description: >- Canadian Suitability Limit (CAD SL) exceeded type: object properties: reason: type: string enum: - canadian_suitability_limit_exceeded required: - reason - description: >- There are restrictions on the user account that can be lifted over time without action on his side. E.g. the user may have been marked a potential fraudster on our side. type: object properties: reason: type: string enum: - user_temporarily_restricted required: - reason - description: >- Also used for deserializing unknown values, in which case the string representation of tha value is appended to the `details`. type: object properties: reason: type: string enum: - other details: type: string required: - details - reason - description: The user's bank account is not supported type: object properties: reason: type: string enum: - bank_account_not_supported required: - reason - description: >- The user's payment method needs to be reauthorized type: object properties: reason: type: string enum: - reauthorization_required required: - reason required: - reason - status required: - action - created_at - id - name - status - trigger - updated_at required: - order '401': $ref: '#/components/responses/UnauthorizedError' '408': $ref: '#/components/responses/RequestTimeoutError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/users: post: operationId: createEmbedUser summary: Create User tags: - Users description: | Create a new user in the Payward system. parameters: - $ref: '#/components/parameters/PaywardVersion' requestBody: content: application/json: schema: type: object properties: email: description: The email associated with the account. type: string format: email external_id: description: >- An external user ID for partners to link their user ID to a Payward account. type: string tos_version_accepted: description: Versions of Payward's Terms of Service accepted by the user type: integer format: int32 full_name: description: User's full name type: object properties: first_name: description: User's first name type: string middle_name: nullable: true description: User's middle name type: string last_name: description: User's last name type: string required: - first_name - last_name date_of_birth: description: User's date of birth type: string format: date residence: description: User's residential address type: object properties: line1: description: Address line 1 type: string line2: nullable: true description: Address line 2 type: string city: description: City type: string postal_code: description: Postal code type: string province: nullable: true description: Province or state type: string country: $ref: '#/components/schemas/CountryCode' required: - city - country - line1 - postal_code phone: description: Phone number in E.164 format type: string pattern: ^\+?[1-9]\d{1,14}$ nationalities: description: User's nationalities type: array items: $ref: '#/components/schemas/CountryCode' occupation: description: User's occupation type: string enum: - agriculture - business_management - computers_and_it - construction - education - finance - government - healthcare - hospitality - manufacturing - marketing - media - other - science - self_employed - student - transportation - unemployed - employed employer_name: nullable: true description: Name of user's employer type: string client_identifier: nullable: true description: Identifier assigned by the partner platform oneOf: - type: object properties: type: type: string enum: - concat value: type: string calculated_at: type: string format: date-time required: - calculated_at - type - value - type: object properties: type: type: string enum: - passport value: type: string required: - type - value - type: object properties: type: type: string enum: - national_id value: type: string required: - type - value - type: object properties: type: type: string enum: - tax_id value: type: string required: - type - value - type: object properties: type: type: string enum: - lei value: type: string required: - type - value - type: object properties: type: type: string enum: - unknown required: - type city_of_birth: nullable: true description: User's city of birth type: string country_of_birth: $ref: '#/components/schemas/CountryCode' description: User's country of birth tax_ids: nullable: true description: User's tax ID type: array items: type: object properties: id: description: Taxpayer identifier type: string issuing_country: $ref: '#/components/schemas/CountryCode' description: Country issuing the tax ID required: - id - issuing_country language: nullable: true description: >- The user's preferred language, as an [ISO 639-1] language code. If not provided, the user's language will be set to the default language for their country. [ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1 type: string required: - date_of_birth - email - external_id - full_name - nationalities - occupation - phone - residence - tos_version_accepted required: true responses: '201': description: Response content: application/json: schema: type: object properties: result: type: object properties: user: $ref: '#/components/schemas/Iiban' description: The generated Payward Public Account ID required: - user '400': description: | Bad Request. Error codes: - `ENexus:Invalid user ID` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '400' code: ENexus:Invalid user ID detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/users/{user}: get: operationId: getEmbedUser tags: - Users summary: Get User description: | Get a previously created user. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: user: description: Payward-assigned account id. type: string minLength: 14 maxLength: 42 external_id: nullable: true description: Optional external ID for the user set by the partner. type: string user_type: description: >- Indicates the type of the user (individual or corporate). type: string enum: - individual - corporate status: description: The overall status of the user. oneOf: - description: User is active and able to use the service. type: object properties: state: type: string enum: - ok required_actions: description: >- Actions that are required and have not been completed, but are not blocking. type: array items: description: >- An action that a user must complete (or wait for) before they can use the service. Some actions are blocking and must be completed before the user can use the service, while others are non-blocking and can be completed at any time. Actions can have deadlines, after which the user may be disabled or closed. oneOf: - description: Additional verification is required. type: object properties: action_type: type: string enum: - verification verification_type: description: Type of verification required. type: string enum: - identity - residence - selfie - sanctions_check - pep_check - negative_news_check - tax_id reasons: description: Reason why verification is required. type: array items: anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: nullable: true description: >- Deadline for completing the verification, if any. type: string format: date-time required: - action_type - reasons - verification_type - description: Additional details are required. type: object properties: action_type: type: string enum: - provide_details details_type: description: Type of details required. oneOf: - description: Terms of service type: object properties: type: type: string enum: - terms_of_service version: description: >- The version of the terms of service that the user has accepted. type: integer format: uint32 minimum: 0 required: - type - version - description: User's full name type: object properties: type: type: string enum: - full_name required: - type - description: User's date of birth type: object properties: type: type: string enum: - date_of_birth required: - type - description: User's city of birth type: object properties: type: type: string enum: - city_of_birth required: - type - description: User's country of birth type: object properties: type: type: string enum: - country_of_birth required: - type - description: User's nationalities type: object properties: type: type: string enum: - nationalities required: - type - description: User's residential address type: object properties: type: type: string enum: - residence required: - type - description: User's phone number type: object properties: type: type: string enum: - phone required: - type - description: User's occupation type: object properties: type: type: string enum: - occupation required: - type - description: User's tax IDs type: object properties: type: type: string enum: - tax_ids required: - type - description: Name of user's employer type: object properties: type: type: string enum: - employer required: - type - description: Client identifier assigned by partner type: object properties: type: type: string enum: - client_identifier required: - type reason: nullable: true description: Reason why details are required. anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: nullable: true description: >- Deadline for providing the details, if any. type: string format: date-time required: - action_type - details_type - description: >- User must wait before using KPay. Typically when Payward is performing additional checks. type: object properties: action_type: type: string enum: - wait wait_reason_code: description: Reason why the user must wait. type: string required: - action_type - wait_reason_code required: - required_actions - state - description: User is disabled and cannot use the service. type: object properties: state: type: string enum: - disabled reasons: description: Reason codes for why the user is disabled. type: array items: anyOf: - type: string enum: - tos_not_accepted - tos_rejected - missing_required_verifications - missing_required_details - pending_verifications - suspicious_activity - description: A catch-all for other reasons. type: string required_actions: description: >- Required actions that must be completed before the user can use KPay again. type: array items: description: >- An action that a user must complete (or wait for) before they can use the service. Some actions are blocking and must be completed before the user can use the service, while others are non-blocking and can be completed at any time. Actions can have deadlines, after which the user may be disabled or closed. oneOf: - description: Additional verification is required. type: object properties: action_type: type: string enum: - verification verification_type: description: Type of verification required. type: string enum: - identity - residence - selfie - sanctions_check - pep_check - negative_news_check - tax_id reasons: description: Reason why verification is required. type: array items: anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: nullable: true description: >- Deadline for completing the verification, if any. type: string format: date-time required: - action_type - reasons - verification_type - description: Additional details are required. type: object properties: action_type: type: string enum: - provide_details details_type: description: Type of details required. oneOf: - description: Terms of service type: object properties: type: type: string enum: - terms_of_service version: description: >- The version of the terms of service that the user has accepted. type: integer format: uint32 minimum: 0 required: - type - version - description: User's full name type: object properties: type: type: string enum: - full_name required: - type - description: User's date of birth type: object properties: type: type: string enum: - date_of_birth required: - type - description: User's city of birth type: object properties: type: type: string enum: - city_of_birth required: - type - description: User's country of birth type: object properties: type: type: string enum: - country_of_birth required: - type - description: User's nationalities type: object properties: type: type: string enum: - nationalities required: - type - description: User's residential address type: object properties: type: type: string enum: - residence required: - type - description: User's phone number type: object properties: type: type: string enum: - phone required: - type - description: User's occupation type: object properties: type: type: string enum: - occupation required: - type - description: User's tax IDs type: object properties: type: type: string enum: - tax_ids required: - type - description: Name of user's employer type: object properties: type: type: string enum: - employer required: - type - description: Client identifier assigned by partner type: object properties: type: type: string enum: - client_identifier required: - type reason: nullable: true description: Reason why details are required. anyOf: - type: string enum: - initial_onboarding - description: A catch-all for other reasons. type: string deadline: nullable: true description: >- Deadline for providing the details, if any. type: string format: date-time required: - action_type - details_type - description: >- User must wait before using KPay. Typically when Payward is performing additional checks. type: object properties: action_type: type: string enum: - wait wait_reason_code: description: Reason why the user must wait. type: string required: - action_type - wait_reason_code required: - reasons - required_actions - state - description: User is closed and cannot use the service. type: object properties: state: type: string enum: - closed reasons: description: >- Reason codes for why the user account is closed. type: array items: anyOf: - type: string enum: - verification_failed - tos_violation - description: A catch-all for other reasons. type: string required: - reasons - state created_at: description: >- The datetime when the user was created in ISO 8601 format. type: string format: date-time required: - created_at - status - user - user_type '400': description: | Bad Request. Error codes: - `ENexus:Invalid user ID` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '400' code: ENexus:Invalid user ID detail: null result: null '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' patch: operationId: updateEmbedUser summary: Update User tags: - Users description: | Update an existing user's profile. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' requestBody: content: application/json: schema: type: object properties: tos_version_accepted: nullable: true description: Versions of Payward's Terms of Service accepted by the user type: integer format: int32 full_name: nullable: true description: User's full name type: object properties: first_name: description: User's first name type: string middle_name: nullable: true description: User's middle name type: string last_name: description: User's last name type: string required: - first_name - last_name date_of_birth: nullable: true description: User's date of birth type: string format: date city_of_birth: nullable: true description: User's city of birth type: string country_of_birth: nullable: true description: User's country of birth type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C residence: nullable: true description: User's residential address type: object properties: line1: description: Address line 1 type: string line2: nullable: true description: Address line 2 type: string city: description: City type: string postal_code: description: Postal code type: string province: nullable: true description: Province or state type: string country: description: Country type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C required: - city - country - line1 - postal_code phone: nullable: true description: Phone number in E.164 format type: string pattern: ^\+?[1-9]\d{1,14}$ nationalities: nullable: true description: User's nationalities type: array items: description: An ISO 3166-1 alpha-2 country code type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C tax_ids: nullable: true description: User's tax ID type: array items: type: object properties: id: description: Taxpayer identifier type: string issuing_country: description: Country issuing the tax ID type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C required: - id - issuing_country occupation: nullable: true description: User's occupation type: string enum: - agriculture - business_management - computers_and_it - construction - education - finance - government - healthcare - hospitality - manufacturing - marketing - media - other - science - self_employed - student - transportation - unemployed - employed employer_name: nullable: true description: Name of user's employer type: string client_identifier: nullable: true description: Identifier assigned by the partner platform oneOf: - type: object properties: type: type: string enum: - concat value: type: string calculated_at: type: string format: date-time required: - calculated_at - type - value - type: object properties: type: type: string enum: - passport value: type: string required: - type - value - type: object properties: type: type: string enum: - national_id value: type: string required: - type - value - type: object properties: type: type: string enum: - tax_id value: type: string required: - type - value - type: object properties: type: type: string enum: - lei value: type: string required: - type - value - type: object properties: type: type: string enum: - unknown required: - type language: nullable: true description: >- The user's preferred language, as an [ISO 639-1] language code. If not provided, the user's language will be set to the default language for their country. [ISO 639-1]: https://en.wikipedia.org/wiki/ISO_639-1 type: string required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: string enum: - success '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/subaccounts: post: operationId: createHeadlessEmbedSubaccount summary: Create Headless Subaccount tags: - Subaccounts description: > Create a new headless subaccount in the Payward system. A headless subaccount is a lightweight account that only requires an external ID mapping, without any user profile data (email, name, phone, etc.). This is useful for partners who manage user data entirely on their side. **Note:** The availability of this endpoint depends on your licensing agreement. Only partners with the relevant licenses in their operating jurisdiction can choose not to share KYC data with Payward. If you need to create a user with full profile data for KYC verification, use the [Create User](/docs/embed-api/create-embed-user) endpoint instead. parameters: - $ref: '#/components/parameters/PaywardVersion' requestBody: content: application/json: schema: type: object properties: external_id: description: > A unique external user ID for partners to link their user ID to a Payward account. This ID must be unique within your partner account. type: string example: partner-user-12345 required: - external_id required: true responses: '200': description: Subaccount created successfully content: application/json: schema: type: object properties: result: type: object properties: user: type: string description: The generated Payward Public Account ID (IIBAN) example: AA95 N84G TEST XXXX required: - user '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/verifications/{user}: post: operationId: submitEmbedVerification summary: Submit Verification tags: - Verifications description: > Submit a verification for a user with documents and details. A verification is defined as a check that has been performed on a user to verify information provided by the user. This is typically done by a third party, such as a company that specializes in identity verification. Checks are most commonly performed on documents provided by the user, such as a passport or driver's license, but can also include other types of checks such as a sanctions check or a Politically Exposed Person (PEP) check. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' requestBody: content: multipart/form-data: schema: oneOf: - type: object properties: type: type: string enum: - identity_document metadata: description: Metadata about the verification. type: object properties: identity: description: The identity of the person in the document type: object properties: full_name: description: User's full name type: object properties: first_name: description: User's first name type: string middle_name: nullable: true description: User's middle name type: string last_name: description: User's last name type: string required: - first_name - last_name date_of_birth: example: '2023-03-13' description: User's date of birth type: string required: - date_of_birth - full_name document_type: description: Type of identity document type: string enum: - passport - drivers_license - id_card - residence_card - special_permanent_residence_card document_number: description: >- Number of the document (e.g. driver's license number) type: string issuing_country: description: Country of issuance of the identity document type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C nationality: nullable: true description: >- Nationality of the identified person according to the document type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - document_number - document_type - identity - issuing_country - verified_at - verifier front: description: File containing front side of the identity document type: string format: binary back: description: File containing back side of the identity document type: string format: binary verifier_response: description: >- File containing document verification vendor response (if applicable) type: string format: binary required: - front - metadata - type - type: object properties: type: type: string enum: - residence_document metadata: description: Metadata about the verification. type: object properties: address: description: The address captured in this document type: object properties: line1: description: Address line 1 type: string line2: nullable: true description: Address line 2 type: string city: description: City type: string postal_code: description: Postal code type: string province: nullable: true description: Province or state type: string country: description: Country type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C required: - city - country - line1 - postal_code document_type: description: Type of residence verification document type: string enum: - bank_statement - credit_card_statement - employer_letter_or_work_contract - government_issued_document - home_or_rental_insurance - internet_or_cable_bill - mobile_phone_bill - mortgage_statement - official_government_letter - passport_address_page - rental_or_lease_agreement - residence_certificate - social_insurance_payment_receipt - tax_receipt - tax_return - utility_bill - other document_number: nullable: true description: >- Number of the document (e.g. driver's license number) type: string verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - address - document_type - verified_at - verifier document: description: File containing proof of residence document type: string format: binary verifier_response: description: >- File containing document verification vendor response (if applicable) type: string format: binary required: - document - metadata - type - type: object properties: type: type: string enum: - selfie metadata: description: Metadata about the verification. type: object properties: selfie_type: description: Type of selfie type: string enum: - selfie - selfie_capture_video verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - selfie_type - verified_at - verifier selfie: description: File containing selfie type: string format: binary verifier_response: description: >- File containing document verification vendor response (if applicable) type: string format: binary required: - metadata - selfie - type required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: verification_id: description: Internal ID of the verification. type: string required: - verification_id '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/verifications/{user}/url: post: operationId: submitEmbedVerificationFromUrl summary: Submit Verification from URL tags: - Verifications description: > Submit a verification for a user with documents provided via presigned URLs. Instead of uploading files directly via multipart form data, this endpoint accepts presigned URLs pointing to your document files. The server will download the files from the provided URLs and process them. The filename will be extracted from each URL path. This is useful when your documents are already stored in a cloud storage provider (e.g. AWS S3, Google Cloud Storage) and you want to avoid re-uploading them. A verification is defined as a check that has been performed on a user to verify information provided by the user. This is typically done by a third party, such as a company that specializes in identity verification. Checks are most commonly performed on documents provided by the user, such as a passport or driver's license, but can also include other types of checks such as a sanctions check or a Politically Exposed Person (PEP) check. ## Domain allowlisting For security, the domains you use for presigned URLs must be allowlisted before you can use this endpoint. Contact your account manager to configure the allowed domains for your integration. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/UserPath' requestBody: content: application/json: schema: oneOf: - type: object properties: type: type: string enum: - identity_document metadata: description: Metadata about the verification. type: object properties: identity: description: The identity of the person in the document type: object properties: full_name: description: User's full name type: object properties: first_name: description: User's first name type: string middle_name: nullable: true description: User's middle name type: string last_name: description: User's last name type: string required: - first_name - last_name date_of_birth: example: '2023-03-13' description: User's date of birth type: string required: - date_of_birth - full_name document_type: description: Type of identity document type: string enum: - passport - drivers_license - id_card - residence_card - special_permanent_residence_card document_number: description: >- Number of the document (e.g. driver's license number) type: string issuing_country: description: Country of issuance of the identity document type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C nationality: nullable: true description: >- Nationality of the identified person according to the document type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - document_number - document_type - identity - issuing_country - verified_at - verifier front_url: description: >- Presigned URL to the front side of the identity document. The filename will be extracted from the URL path. type: string back_url: nullable: true description: >- Presigned URL to the back side of the identity document (optional). The filename will be extracted from the URL path. type: string verifier_response_url: nullable: true description: >- Presigned URL to the verifier response document (optional). The filename will be extracted from the URL path. type: string required: - front_url - metadata - type - type: object properties: type: type: string enum: - residence_document metadata: description: Metadata about the verification. type: object properties: address: description: The address captured in this document type: object properties: line1: description: Address line 1 type: string line2: nullable: true description: Address line 2 type: string city: description: City type: string postal_code: description: Postal code type: string province: nullable: true description: Province or state type: string country: description: Country type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW - AC - AN - AP - CP - DG - EA - EU - IC - JX - TA - QO - XK - 0C required: - city - country - line1 - postal_code document_type: description: Type of residence verification document type: string enum: - bank_statement - credit_card_statement - employer_letter_or_work_contract - government_issued_document - home_or_rental_insurance - internet_or_cable_bill - mobile_phone_bill - mortgage_statement - official_government_letter - passport_address_page - rental_or_lease_agreement - residence_certificate - social_insurance_payment_receipt - tax_receipt - tax_return - utility_bill - other document_number: nullable: true description: >- Number of the document (e.g. driver's license number) type: string verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - address - document_type - verified_at - verifier document_url: description: >- Presigned URL to the residence document. The filename will be extracted from the URL path. type: string verifier_response_url: nullable: true description: >- Presigned URL to the verifier response document (optional). The filename will be extracted from the URL path. type: string required: - document_url - metadata - type - type: object properties: type: type: string enum: - selfie metadata: description: Metadata about the verification. type: object properties: selfie_type: description: Type of selfie type: string enum: - selfie - selfie_capture_video verifier: description: Name of the verification provider. type: string verified_at: example: '2023-03-13T12:34:56Z' description: The date and time the verification was completed type: string verifier_response: nullable: true description: Response from the verifier external_verification_id: nullable: true description: >- External document id of the verification that can be provided by the partner type: string expiration_date: nullable: true example: '2023-03-13' description: >- Optional expiration date of the verification when it is no longer valid in ISO 8601 format. type: string required: - selfie_type - verified_at - verifier selfie_url: description: >- Presigned URL to the selfie. The filename will be extracted from the URL path. type: string verifier_response_url: nullable: true description: >- Presigned URL to the verifier response document (optional). The filename will be extracted from the URL path. type: string required: - metadata - selfie_url - type required: true responses: '200': description: Response content: application/json: schema: type: object properties: result: nullable: true type: object properties: verification_id: description: Internal ID of the verification. type: string required: - verification_id '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/reports/settlement: get: operationId: listEmbedSettlementReports summary: List Settlement Reports description: >- Retrieves a paginated list of settlement reports available to the authenticated master user, with optional filters for date range and report type. tags: - Reports parameters: - $ref: '#/components/parameters/PaywardVersion' - in: query name: filter[start_date] description: >- The inclusive start date for filtering settlement reports. Use in combination with `filter[end_date]` to specify a date range. Format: RFC 3339 datetime. schema: type: string format: date-time nullable: true example: '2025-06-30T00:00:00.000Z' style: form allowEmptyValue: true - in: query name: filter[end_date] description: >- The inclusive end date for filtering settlement reports. Use in combination with `filter[start_date]` to specify a date range. Format: RFC 3339 datetime. schema: type: string format: date-time nullable: true example: '2025-07-01T00:00:00.000Z' style: form allowEmptyValue: true - in: query name: filter[report_type][] description: >- Filters the returned reports by one or more report types. If omitted, all report types are included. schema: type: array items: type: string enum: - trades - transfers - earn_rewards default: [] style: form explode: true allowEmptyValue: true - in: query name: page[size] description: >- The maximum number of reports to return per page. Must be between 1 and 100. schema: type: integer format: uint32 minimum: 1 maximum: 100 default: 20 style: form allowEmptyValue: true - in: query name: page[number] description: The page of results to retrieve. Must be 1 or greater. schema: type: integer format: uint32 minimum: 1 default: 1 style: form allowEmptyValue: true responses: '200': description: >- Successful response containing a list of settlement reports and pagination details. content: application/json: schema: type: object properties: result: nullable: true type: object properties: reports: description: >- An array of settlement report objects that match the specified filter criteria. type: array items: type: object properties: id: description: >- A unique identifier assigned to each settlement report. type: string date: description: >- The date covered by the report, spanning from 00:00:00 UTC to 23:59:59 UTC. type: string format: date type: description: The category of the report. type: string enum: - trades - transfers - earn_rewards size: description: The file size of the report, in bytes. type: integer format: int64 name: description: >- A descriptive, human-readable name for the report. type: string required: - date - id - name - size - type links: description: URLs for navigating between pages of results. type: object properties: self: nullable: true type: string first: nullable: true type: string last: nullable: true type: string prev: nullable: true type: string next: nullable: true type: string meta: description: >- Metadata about the pagination of the results, including total items, total pages, page size, and current page number. type: object properties: total_items: nullable: true type: integer format: uint32 minimum: 0 total_pages: nullable: true type: integer format: uint32 minimum: 0 page_size: nullable: true type: integer format: uint32 minimum: 0 page_number: nullable: true type: integer format: uint32 minimum: 0 required: - links - meta - reports '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/reports/settlement/{id}: get: operationId: getEmbedSettlementReport summary: Get Settlement Report description: >- Retrieves a settlement report and provides a secure download URL for the authenticated master user. tags: - Reports parameters: - $ref: '#/components/parameters/PaywardVersion' - in: path name: id required: true description: The unique identifier of the settlement report to retrieve. schema: type: string style: simple responses: '200': description: >- Successful response containing the settlement report details and secure download URL. content: application/json: schema: type: object properties: result: nullable: true type: object properties: id: description: >- A unique identifier assigned to each settlement report. type: string date: description: >- The date covered by the report, spanning from 00:00:00 UTC to 23:59:59 UTC. type: string format: date type: description: The category of the report. type: string enum: - trades - transfers - earn_rewards size: description: The file size of the report, in bytes. type: integer format: int64 minimum: 0 name: description: A descriptive, human-readable name for the report. type: string download_url: description: >- A secure URL to download the settlement report document. The URL is valid until the `expires_at` timestamp and can be used directly in HTTP requests or browser downloads without additional authentication headers. type: string expires_at: description: >- When the download URL expires. The URL becomes invalid after this timestamp. Clients should request a new URL if they need to download the report after this time. type: string format: date-time required: - id - date - type - size - name - download_url - expires_at required: - error - errors '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': description: | Not Found. Error codes: - `ENexus:Report not found` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '404' code: ENexus:Report not found detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/webhooks: get: operationId: listEmbedWebhooks summary: List Webhooks tags: - Webhooks description: > Retrieve all webhooks registered for your domain. This endpoint returns the full webhook configuration including subscribed events and all available event types for each webhook. **Note:** The webhook `secret` is NOT included in this response. The secret is only returned once during registration and cannot be retrieved again. parameters: - $ref: '#/components/parameters/PaywardVersion' responses: '200': description: Webhooks retrieved successfully content: application/json: schema: type: object properties: result: type: object properties: webhooks: type: array description: > List of webhooks registered for this domain. Currently limited to 1 webhook per domain, but returns an array for future expansion. items: type: object properties: id: type: string description: Unique identifier for the webhook example: WHTEST-XXXXX-EXAMPLE url: type: string format: uri description: The registered webhook URL example: https://example.com/webhook enabled: type: boolean description: Whether the webhook is enabled example: true subscribed_events: type: array description: >- List of event types this webhook is subscribed to items: type: string example: - quote.executed available_events: type: array description: >- All available event types that can be subscribed to items: type: string example: - custom_order.executed - custom_order.execution_failed - custom_order.cancelled - quote.executed - quote.execution_failed - quote.cancelled - reward.paid - user.verified - user.closed - user.disabled created_at: type: string format: date-time description: When the webhook was created example: '2023-01-01T00:00:00Z' updated_at: type: string format: date-time description: When the webhook was last updated example: '2023-01-01T00:00:00Z' required: - id - url - enabled - subscribed_events - available_events - created_at - updated_at required: - webhooks '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' post: operationId: registerEmbedWebhook summary: Register Webhook tags: - Webhooks description: > Register a new webhook endpoint to receive event notifications from Payward Embed. When you register a webhook, you'll receive a `secret` in the response. This secret is **base64-encoded** and is used to verify webhook signatures. Store it securely — it is only returned once and cannot be retrieved again. Before registering a webhook, make sure your callback domain has been allowlisted. You can optionally specify `enabled` and `events` at registration time, or configure them later using the **Update Webhook** endpoint. ## URL Requirements - Must use HTTPS protocol - Maximum length: 2048 characters - Must be a valid URL format - Must have a valid host (not empty) - Host cannot be a protocol name (e.g., `http`, `https`, `ftp`, `file`, `mailto`, `ssh`, `git`, `svn`) - Path cannot start with `//` (indicates malformed URL) - Cannot contain credentials (e.g., `https://user:pass@example.com` is rejected) ### Valid URL Examples - `https://example.com/webhook` - `https://example.com:8443/webhook` ### Invalid URL Examples - `http://example.com/webhook` (HTTP not allowed) - `https://https//example.com` (malformed - host is "https") - `https://user:pass@example.com/webhook` (credentials not allowed) - `invalid-url` (not a valid URL) parameters: - $ref: '#/components/parameters/PaywardVersion' requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri maxLength: 2048 description: > The HTTPS URL where webhook events will be sent. This endpoint must be publicly accessible and respond to POST requests. example: https://your-domain.com/webhooks/payward enabled: type: boolean default: false description: > Whether the webhook is enabled. Defaults to `false`. Disabled webhooks will not receive any events until enabled. example: true events: type: array default: [] description: > List of event types to subscribe to. Defaults to `[]` (no events). Use this to configure which events trigger webhook notifications. items: type: string pattern: ^[a-zA-Z0-9._]+$ maxLength: 100 minItems: 0 maxItems: 50 example: - quote.executed required: - url responses: '200': description: Webhook registered successfully content: application/json: schema: type: object properties: result: type: object properties: webhook: type: object description: The created webhook configuration properties: id: type: string description: Unique identifier for the webhook example: WHTEST-XXXXX-EXAMPLE url: type: string format: uri description: The registered webhook URL example: https://your-domain.com/webhooks/payward enabled: type: boolean description: >- Whether the webhook is enabled. Defaults to `false`. example: false subscribed_events: type: array description: List of event types this webhook is subscribed to items: type: string example: [] available_events: type: array description: >- All available event types that can be subscribed to items: type: string example: - custom_order.executed - custom_order.execution_failed - custom_order.cancelled - quote.executed - quote.execution_failed - quote.cancelled - reward.paid - user.verified - user.closed - user.disabled - deposit.status_updated - withdrawal.status_updated created_at: type: string format: date-time description: When the webhook was created example: '2023-01-01T00:00:00Z' updated_at: type: string format: date-time description: When the webhook was last updated example: '2023-01-01T00:00:00Z' required: - id - url - enabled - subscribed_events - available_events - created_at - updated_at secret: type: string description: > Base64-encoded HMAC secret for webhook signature verification. **Important:** This secret is only returned once. Store it securely as it cannot be retrieved again. You'll need this secret to verify webhook signatures on incoming events. example: dGVzdC1zZWNyZXQtcGxlYXNlLWlnbm9yZQ== required: - webhook - secret '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': description: | Conflict. Error codes: - `ENexus:Webhook already exists` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '409' code: ENexus:Webhook already exists detail: null result: null '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/webhooks/{webhook_id}: patch: operationId: updateEmbedWebhook summary: Update Webhook tags: - Webhooks description: > Update a webhook's enabled status and/or event subscriptions. Use this endpoint to: - Enable or disable a webhook without deleting it - Update which events the webhook is subscribed to Disabled webhooks will not receive any events until re-enabled. **Note:** The webhook URL cannot be updated. To change the URL, delete the webhook and register a new one. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/WebhookIdPath' requestBody: required: true content: application/json: schema: type: object properties: enabled: type: boolean description: Whether the webhook should be enabled or disabled example: true events: type: array description: > List of event types to subscribe to. This **replaces** all existing event subscriptions. Pass an empty array `[]` to unsubscribe from all events. items: type: string pattern: ^[a-zA-Z0-9._]+$ maxLength: 100 minItems: 0 maxItems: 50 example: - quote.executed responses: '200': description: Webhook updated successfully content: application/json: schema: type: object properties: result: type: object properties: webhook: type: object description: The updated webhook configuration properties: id: type: string description: Unique identifier for the webhook example: WHTEST-XXXXX-EXAMPLE url: type: string format: uri description: The registered webhook URL example: https://your-domain.com/webhooks/payward enabled: type: boolean description: Whether the webhook is enabled example: true subscribed_events: type: array description: List of event types this webhook is subscribed to items: type: string example: - quote.executed available_events: type: array description: >- All available event types that can be subscribed to items: type: string example: - custom_order.executed - custom_order.execution_failed - custom_order.cancelled - quote.executed - quote.execution_failed - quote.cancelled - reward.paid - user.verified - user.closed - user.disabled created_at: type: string format: date-time description: When the webhook was created example: '2023-01-01T00:00:00Z' updated_at: type: string format: date-time description: When the webhook was last updated example: '2023-01-01T00:01:00Z' required: - id - url - enabled - subscribed_events - available_events - created_at - updated_at required: - webhook '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': description: | Not Found. Error codes: - `ENexus:Webhook not found` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '404' code: ENexus:Webhook not found detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' delete: operationId: deleteEmbedWebhook summary: Delete Webhook tags: - Webhooks description: > Delete a webhook configuration. This permanently removes the webhook and all its event subscriptions. No further events will be delivered to the webhook URL. **Note:** This action cannot be undone. If you want to temporarily stop receiving events, consider using the **Update Webhook** endpoint to disable the webhook instead. parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/WebhookIdPath' responses: '200': description: Webhook deleted successfully content: application/json: schema: type: object properties: result: type: object properties: webhook_id: type: string description: The ID of the deleted webhook example: WHTEST-XXXXX-EXAMPLE deleted_at: type: string format: date-time description: When the webhook was deleted example: '2025-01-15T14:00:00Z' required: - webhook_id - deleted_at '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /b2b/webhooks/{webhook_id}/test: post: operationId: testEmbedWebhook summary: Test Webhook tags: - Webhooks description: > Send a test event to verify your webhook configuration. This endpoint sends a test event to your configured webhook URL, allowing you to verify that: - Your endpoint is reachable - Your signature verification is working correctly - Your endpoint responds appropriately The test event will include a real HMAC signature that you can verify using your webhook secret. ## Test Event Payload The test event has the following structure: ```json { "event_type": "webhook.test", "message": "This is a test webhook event to verify your endpoint configuration." } ``` ## Error Handling | Error Type | Message | When | |------------|---------|------| | `Webhook not found` | The webhook ID doesn't exist or belongs to a different domain | | `Webhook is disabled` | The webhook exists but is not enabled (`enabled: false`) | parameters: - $ref: '#/components/parameters/PaywardVersion' - $ref: '#/components/parameters/WebhookIdPath' responses: '200': description: Test webhook sent (check result for delivery status) content: application/json: schema: type: object properties: result: type: object properties: result: type: string description: Result of the test delivery enum: - success - failed example: success test_id: type: string format: uuid description: Unique test ID for tracking in logs example: 550e8400-e29b-41d4-a716-446655440000 http_status: type: integer nullable: true description: HTTP status code returned by your webhook endpoint example: 200 response_body: type: string nullable: true description: Response body from your endpoint (truncated to 1KB) example: OK error_message: type: string nullable: true description: Error message if delivery failed example: null payload_sent: type: string description: The JSON payload that was sent to your webhook example: >- {"event_type":"webhook.test","message":"This is a test webhook event to verify your endpoint configuration."} signature_header: type: string description: | The signature header that was sent. Use this to debug signature verification issues. example: t=1234567890,v1=abc123def456... required: - result - test_id - payload_sent - signature_header '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': description: | Forbidden. Error codes: - `ENexus:Webhook is disabled` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '403' code: ENexus:Webhook is disabled detail: null result: null '404': description: | Not Found. Error codes: - `ENexus:Webhook not found` — not retryable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - status: '404' code: ENexus:Webhook not found detail: null result: null '408': $ref: '#/components/responses/RequestTimeoutError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailableError' /webhooks/payward/events: post: operationId: embedWebhookEvents summary: Webhook Events tags: - Webhooks servers: - url: https://your-webhook-endpoint.com description: Partner-provided webhook endpoint security: [] description: > **This endpoint should be implemented by the partner** to receive real-time event notifications from Payward Embed. When specific events occur (such as a quote being executed), Payward sends a POST request to your configured webhook URL with event details. ## Security All webhook requests include an `X-Signature` header containing a timestamped HMAC-SHA256 signature. Partners should verify this signature to ensure the authenticity and integrity of the request. ### Signature Header Format The signature header follows the format: ``` t={timestamp},v1={signature} ``` Where: - `t` - Unix timestamp (seconds) when the webhook was sent - `v1` - Hex-encoded HMAC-SHA256 signature Example header: ``` X-Signature: t=1734567890,v1=5f2b3c4d1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d ``` ### Signature Verification To verify the webhook signature: 1. Extract the timestamp (`t`) and signature (`v1`) from the `X-Signature` header 2. Construct the signed payload by concatenating: `{timestamp}.{raw_request_body}` 3. Base64-decode your webhook secret (received when registering the webhook) 4. Compute HMAC-SHA256 of the signed payload using the decoded secret 5. Compare the computed signature (hex-encoded) with the `v1` value from the header ```typescript import crypto from 'crypto'; interface ParsedSignature { timestamp: number; signatures: string[]; } // Parse the X-Signature header function parseSignatureHeader(header: string): ParsedSignature | null { let timestamp: number | null = null; const signatures: string[] = []; for (const part of header.split(',')) { if (part.startsWith('t=')) { timestamp = parseInt(part.slice(2), 10); } else if (part.startsWith('v1=')) { signatures.push(part.slice(3)); } } if (timestamp === null) return null; return { timestamp, signatures }; } // Verify the webhook signature function verifyWebhookSignature( signatureHeader: string, body: string, secretBase64: string ): boolean { const parsed = parseSignatureHeader(signatureHeader); if (!parsed || parsed.signatures.length === 0) { return false; } // Construct signed payload: {timestamp}.{body} const signedPayload = `${parsed.timestamp}.${body}`; // Decode base64 secret const secretBytes = Buffer.from(secretBase64, 'base64'); // Compute HMAC-SHA256 const computedSignature = crypto .createHmac('sha256', secretBytes) .update(signedPayload) .digest('hex'); // Compare with provided signatures (constant-time comparison recommended) return parsed.signatures.some(sig => crypto.timingSafeEqual( Buffer.from(computedSignature), Buffer.from(sig) ) ); } ``` ### Timestamp Validation The timestamp in the signature header indicates when the webhook was sent. To prevent replay attacks, you should: 1. Parse the timestamp from the `X-Signature` header 2. Compare it against the current time 3. Reject webhooks with timestamps older than your tolerance window (e.g., 5 minutes) ```typescript function isTimestampValid(timestamp: number, toleranceSeconds: number = 300): boolean { const currentTime = Math.floor(Date.now() / 1000); return Math.abs(currentTime - timestamp) <= toleranceSeconds; } ``` ## Event Types | Event Type | Description | |------------|-------------| | `custom_order.executed` | A custom order has been successfully executed | | `custom_order.execution_failed` | A custom order execution has failed | | `custom_order.cancelled` | A custom order was cancelled | | `quote.executed` | A quote has been successfully executed | | `quote.execution_failed` | A quote execution has failed | | `quote.cancelled` | A quote was cancelled before execution | | `deposit.status_updated` | The status of a deposit has been updated | | `withdrawal.status_updated` | The status of a withdrawal has been updated | | `user.verified` | A user has been verified and can now trade on the platform | | `user.closed` | A user's account has been permanently closed | | `user.disabled` | A user's account has been disabled (e.g., due to a trade lock or account suspension) | | `reward.paid` | An Earn reward has been paid to a user | | `webhook.test` | A test event sent via the Test Webhook endpoint | ## Headers All webhook requests include these headers: | Header | Description | |--------|-------------| | `Content-Type` | Always `application/json` | | `X-Signature` | Timestamped HMAC-SHA256 signature (format: `t={timestamp},v1={signature}`) | | `X-Webhook-Event` | The event type (e.g., `quote.executed`) | | `X-Webhook-ID` | The webhook configuration ID | parameters: - in: header name: X-Signature required: true description: > Timestamped HMAC-SHA256 signature in the format `t={timestamp},v1={signature}`. Use this to verify the webhook authenticity and prevent replay attacks. schema: type: string example: >- t=1734567890,v1=5f2b3c4d1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d - in: header name: X-Webhook-Event required: true description: The type of event that triggered this webhook. schema: type: string example: quote.executed - in: header name: X-Webhook-ID required: true description: The ID of the webhook configuration that received this event. schema: type: string example: WHTEST-XXXXX-EXAMPLE - in: header name: Content-Type required: true schema: type: string enum: - application/json requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CustomOrderExecutedEvent' - $ref: '#/components/schemas/CustomOrderExecutionFailedEvent' - $ref: '#/components/schemas/CustomOrderCancelledEvent' - $ref: '#/components/schemas/QuoteExecutedEvent' - $ref: '#/components/schemas/QuoteExecutionFailedEvent' - $ref: '#/components/schemas/QuoteCancelledEvent' - $ref: '#/components/schemas/DepositStatusUpdatedEvent' - $ref: '#/components/schemas/WithdrawalStatusUpdatedEvent' - $ref: '#/components/schemas/UserVerifiedEvent' - $ref: '#/components/schemas/UserClosedEvent' - $ref: '#/components/schemas/UserDisabledEvent' - $ref: '#/components/schemas/RewardPaidEvent' - $ref: '#/components/schemas/WebhookTestEvent' discriminator: propertyName: event_type mapping: custom_order.executed: '#/components/schemas/CustomOrderExecutedEvent' custom_order.execution_failed: '#/components/schemas/CustomOrderExecutionFailedEvent' custom_order.cancelled: '#/components/schemas/CustomOrderCancelledEvent' quote.executed: '#/components/schemas/QuoteExecutedEvent' quote.execution_failed: '#/components/schemas/QuoteExecutionFailedEvent' quote.cancelled: '#/components/schemas/QuoteCancelledEvent' deposit.status_updated: '#/components/schemas/DepositStatusUpdatedEvent' withdrawal.status_updated: '#/components/schemas/WithdrawalStatusUpdatedEvent' user.verified: '#/components/schemas/UserVerifiedEvent' user.closed: '#/components/schemas/UserClosedEvent' user.disabled: '#/components/schemas/UserDisabledEvent' reward.paid: '#/components/schemas/RewardPaidEvent' webhook.test: '#/components/schemas/WebhookTestEvent' examples: custom_order_executed: summary: Custom Order Executed Event value: event_type: custom_order.executed iiban: AA00 TEST EXAM PLE1 id: AEGXGV-JZ4I2-6QXEJS timestamp: '2025-01-15T10:30:00.000000000Z' action: amount: asset: USD amount: '100.00' asset_class: currency quote: asset: BTC type: spend trigger: type: price base_asset: BTC quote_asset: USD target_price: '50000.00' condition: lte execution_details: transaction_id: BQEXAMP-LE123-ABCDEF spend: asset: USD amount: '100.00' asset_class: currency receive: asset: BTC amount: '0.00200000' asset_class: currency total_fee: asset: USD amount: '0.50' asset_class: currency unit_price: asset: USD amount: '50000.00' asset_class: currency executed_at: '2025-01-15T10:30:00.000000000Z' custom_order_execution_failed: summary: Custom Order Execution Failed Event value: event_type: custom_order.execution_failed iiban: AA00 TEST EXAM PLE1 id: AEGXGV-JZ4I2-6QXEJS reason: type: failed detail: insufficient_funds timestamp: '2025-01-15T10:30:00.000000000Z' action: amount: asset: USD amount: '100.00' asset_class: currency quote: asset: BTC type: spend trigger: type: price base_asset: BTC quote_asset: USD target_price: '50000.00' condition: lte custom_order_cancelled: summary: Custom Order Cancelled Event value: event_type: custom_order.cancelled iiban: AA00 TEST EXAM PLE1 id: AEGXGV-JZ4I2-6QXEJS reason: type: cancelled detail: user_request timestamp: '2025-01-15T10:30:00.000000000Z' action: amount: asset: USD amount: '100.00' asset_class: currency quote: asset: BTC type: spend trigger: type: price base_asset: BTC quote_asset: USD target_price: '50000.00' condition: lte quote_executed: summary: Quote Executed Event value: event_type: quote.executed iiban: AA00 TEST EXAM PLE1 quote_id: BQEXAMP-LE123-ABCDEF timestamp: '2025-01-15T10:30:00.000000000Z' quote_execution_failed: summary: Quote Execution Failed Event value: event_type: quote.execution_failed iiban: AA00 TEST EXAM PLE1 quote_id: BQEXAMP-LE123-ABCDEF reason: Insufficient funds timestamp: '2025-01-15T10:30:00.000000000Z' quote_cancelled: summary: Quote Cancelled Event value: event_type: quote.cancelled iiban: AA00 TEST EXAM PLE1 quote_id: BQEXAMP-LE123-ABCDEF reason: Quote expired timestamp: '2025-01-15T10:30:00.000000000Z' deposit_status_updated_received: summary: Deposit Received Event value: event_type: deposit.status_updated iiban: AA00 TEST EXAM PLE1 event: received transaction_id: TX62ZZF-ZYY4I-4QBAUW timestamp: '2025-01-15T10:30:00.000000000Z' deposit_status_updated_credited: summary: Deposit Credited Event value: event_type: deposit.status_updated iiban: AA00 TEST EXAM PLE1 event: credited amount: asset: BTC amount: '0.01000000' asset_class: currency fee: asset: BTC amount: '0.00000000' asset_class: currency transaction_id: TX62ZZF-ZYY4I-4QBAUW timestamp: '2025-01-15T10:30:00.000000000Z' deposit_status_updated_held: summary: Deposit Held Event value: event_type: deposit.status_updated iiban: AA00 TEST EXAM PLE1 event: held reason: aml_check, manual_review transaction_id: TX62ZZF-ZYY4I-4QBAUW timestamp: '2025-01-15T10:30:00.000000000Z' deposit_status_updated_failed: summary: Deposit Failed Event value: event_type: deposit.status_updated iiban: AA00 TEST EXAM PLE1 event: failed reason: manual fail transaction_id: TX62ZZF-ZYY4I-4QBAUW timestamp: '2025-01-15T10:30:00.000000000Z' withdrawal_status_updated_received: summary: Withdrawal Received Event value: event_type: withdrawal.status_updated iiban: AA00 TEST EXAM PLE1 ref_id: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: in_progress event: received timestamp: '2026-02-28T12:00:00.000000000Z' withdrawal_status_updated_held: summary: Withdrawal Held Event value: event_type: withdrawal.status_updated iiban: AA00 TEST EXAM PLE1 ref_id: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: held event: held reasons: - aml_check - manual_review timestamp: '2026-02-28T12:05:00.000000000Z' withdrawal_status_updated_released: summary: Withdrawal Released Event value: event_type: withdrawal.status_updated iiban: AA00 TEST EXAM PLE1 ref_id: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: in_progress event: released timestamp: '2026-02-28T12:10:00.000000000Z' withdrawal_status_updated_complete: summary: Withdrawal Complete Event value: event_type: withdrawal.status_updated iiban: AA00 TEST EXAM PLE1 ref_id: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: successful event: complete timestamp: '2026-02-28T12:15:00.000000000Z' withdrawal_status_updated_failed: summary: Withdrawal Failed Event value: event_type: withdrawal.status_updated iiban: AA00 TEST EXAM PLE1 ref_id: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: failed event: failed reasons: - manual_fail timestamp: '2026-02-28T12:20:00.000000000Z' user_verified: summary: User Verified Event value: event_type: user.verified iiban: AA00 TEST EXAM PLE1 timestamp: '2025-01-15T10:30:00.000000000Z' user_closed: summary: User Closed Event value: event_type: user.closed iiban: AA00 TEST EXAM PLE1 timestamp: '2025-01-15T10:30:00.000000000Z' user_disabled: summary: User Disabled Event value: event_type: user.disabled iiban: AA00 TEST EXAM PLE1 timestamp: '2025-01-15T10:30:00.000000000Z' reward_paid: summary: Reward Paid Event value: event_type: reward.paid iiban: AA00 TEST EXAM PLE1 payout_id: '236191441' asset: ETH amount: '0.0000076470' auto_compound: true timestamp: '2025-01-15T10:30:00.000000000Z' webhook_test: summary: Webhook Test Event value: event_type: webhook.test message: >- This is a test webhook event to verify your endpoint configuration. timestamp: '2025-01-15T10:30:00Z' test_id: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: > Webhook received and processed successfully. Return any 2xx status code to acknowledge receipt. '500': description: | Internal server error on partner side. Payward will retry delivery. components: securitySchemes: API-Key: type: apiKey name: API-Key description: The "API-Key" header should contain your API key. in: header API-Sign: type: apiKey name: API-Sign description: >- Authenticated requests should be signed with the "API-Sign" header, using a signature generated with your private key, nonce, encoded payload, and URI path. in: header parameters: AssetPath: in: path name: asset required: true schema: $ref: '#/components/schemas/AssetName' AssetsFilter: in: query name: filter[assets][] schema: type: array default: [] items: $ref: '#/components/schemas/AssetName' minItems: 0 maxItems: 100 style: form explode: true QuoteIdPath: in: path name: quote_id required: true description: The quote ID generated by `requestEmbedQuote` schema: type: string UserFilter: in: query name: filter[user] schema: $ref: '#/components/schemas/Iiban' UserPath: in: path name: user required: true schema: $ref: '#/components/schemas/Iiban' UserQuery: in: query name: user description: IIBAN of the user to act on behalf of. required: true schema: $ref: '#/components/schemas/Iiban' PaywardVersion: in: header name: Payward-Version description: >- The target version of the Embed API to use. The API version name is based on the date when the API version was released. For example, the API version `2025-04-15` was released on April 15, 2025. schema: default: '2025-04-15' type: string enum: - '2025-04-15' StartDate: in: query name: start_date schema: $ref: '#/components/schemas/Date' EndDate: in: query name: end_date schema: $ref: '#/components/schemas/Date' PageSize: in: query name: page[size] style: form schema: $ref: '#/components/schemas/PageSize' PageNumber: in: query name: page[number] schema: $ref: '#/components/schemas/PageNumber' Quote: in: query name: quote description: | If provided, shows values as the provided asset. schema: $ref: '#/components/schemas/AssetName' default: USD WebhookIdPath: in: path name: webhook_id required: true description: Unique identifier for the webhook schema: type: string example: WHTEST-XXXXX-EXAMPLE Lang: in: query name: lang schema: $ref: '#/components/schemas/Lang' responses: GenericError: description: Generic Error content: application/json: schema: $ref: '#/components/schemas/error' BadRequestError: description: >- Bad Request — the request was malformed or contained invalid parameters. Not retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '400' code: EGeneral:Invalid arguments detail: 'Missing required field: amount' result: null UnauthorizedError: description: >- Unauthorized — authentication failed or credentials are missing/invalid. Not retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '401' code: EAPI:Invalid key detail: null result: null ForbiddenError: description: >- Forbidden — the authenticated user does not have permission to perform this action. Not retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '403' code: EGeneral:Permission denied detail: null result: null NotFoundError: description: Not Found — the requested resource does not exist. Not retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '404' code: EGeneral:Unknown method detail: null result: null RequestTimeoutError: description: Request Timeout — the request took too long to process. Retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '408' code: EGeneral:Timeout detail: null result: null ConflictError: description: >- Conflict — the request conflicts with the current state of the resource. Retryable in some cases (see error code). content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '409' code: EGeneral:Expired detail: null result: null UnprocessableEntityError: description: >- Unprocessable Entity — the request was well-formed but could not be completed due to business logic constraints. Not retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '422' code: EPTL:PTL unable to fund transfer for quote detail: null result: null RateLimitError: description: Too Many Requests — rate limit exceeded. Retryable with backoff. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '429' code: EAPI:Rate limit exceeded detail: null result: null InternalError: description: >- Internal Server Error — an unexpected error occurred. Generally retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '500' code: EGeneral:Internal error detail: null result: null ServiceUnavailableError: description: Service Unavailable — the service is temporarily unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/error' example: errors: - status: '503' code: EService:Unavailable detail: null result: null schemas: ErrorResponse: $ref: '#/components/schemas/error' AssetName: type: string minLength: 3 maxLength: 16 example: BTC AthDate: $ref: '#/components/schemas/Date' description: | The date when the asset reached it's all-time high value. AthValue: $ref: '#/components/schemas/BigDecimal' description: | The all-time high price of the asset. BasisPoints: type: string pattern: ^\d{1,5}$ BigDecimal: type: string format: decimal128 example: '1.23' pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 CirculatingSupply: $ref: '#/components/schemas/BigDecimal' description: | The number of tokens in circulation. CountryCode: {} Date: type: string format: date description: A RFC3339 date (without time) example: '2023-03-13' DateTime: type: string format: date-time description: A RFC 3339 datetime example: '2023-03-13T12:34:56Z' EnglishName: type: string Iiban: type: string description: Internet International Bank Account Number (IIBAN) minLength: 14 maxLength: 42 JsonPointer: type: string format: json-pointer description: RFC6901 JSON Pointer Lang: type: string description: RFC5646 Language Tag default: en pattern: ^([a-zA-Z]{1,8})(-[a-zA-Z\d]{1,8})*$ example: az-Arab-x-AZE-derbend Logo: type: object properties: width: $ref: '#/components/schemas/Uint16' height: $ref: '#/components/schemas/Uint16' href: $ref: '#/components/schemas/Uri' type: $ref: '#/components/schemas/MediaRange' required: - height - href - width MarketCapValue: $ref: '#/components/schemas/BigDecimal' description: | The market cap value, in the `quote` asset provided in the request. MaxSupply: $ref: '#/components/schemas/BigDecimal' description: | The maximum number of tokens that can ever exist. MediaRange: type: string format: media-range PageNumber: type: integer format: uint32 default: 1 minimum: 1 PageSize: type: integer format: uint32 default: 1 minimum: 1 maximum: 100 Percentage: $ref: '#/components/schemas/BigDecimal' Phone: type: string PlatformStatus: description: The global status of an asset on the platform. type: string enum: - enabled - deposit_only - withdrawal_only - funding_temporarily_disabled - disabled PriceTick: type: object properties: timestamp: $ref: '#/components/schemas/DateTime' price: $ref: '#/components/schemas/BigDecimal' required: - price - timestamp TotalSupply: $ref: '#/components/schemas/BigDecimal' description: | The total number of tokens that currently exist. Uint8: type: integer format: uint8 minimum: 0 maximum: 255 Uint16: type: integer format: uint16 minimum: 0 maximum: 65535 Uint32: type: integer format: uint32 minimum: 0 maximum: 4294967295 Uint64: type: integer format: uint32 minimum: 0 maximum: 18446744073709552000 Uri: description: An RFC3986 URI type: string format: uri AssetAmount: type: object description: An asset with its amount and class. properties: asset: type: string description: The asset ticker. example: USD amount: type: string description: The amount as a decimal string. example: '100.00' asset_class: type: string description: The asset class. enum: - currency example: currency required: - asset - amount - asset_class CustomOrderTradeAction: type: object description: The trade action configured for the custom order. properties: amount: $ref: '#/components/schemas/AssetAmount' quote: type: object description: The other asset involved in the trade. properties: asset: type: string description: The asset ticker. example: BTC required: - asset type: type: string description: Whether the amount is quoted in the spend or receive asset. enum: - spend - receive example: spend required: - amount - quote - type PriceTrigger: type: object description: The price trigger that initiated the custom order execution. properties: type: type: string description: The trigger type. enum: - price example: price base_asset: type: string description: The base asset of the price pair being monitored. example: BTC quote_asset: type: string description: The quote asset of the price pair being monitored. example: USD target_price: type: string description: The target price that triggered the action, as a decimal string. example: '50000.00' condition: type: string description: >- The price condition — `lte` (less than or equal) or `gte` (greater than or equal). enum: - lte - gte example: lte required: - type - base_asset - quote_asset - target_price - condition CustomOrderExecutedEvent: type: object description: >- Sent when a custom order has been successfully executed. The order's trade action was triggered by the configured price condition and completed without error. properties: event_type: type: string description: The event type identifier. enum: - custom_order.executed example: custom_order.executed iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose custom order was executed. example: AA00 TEST EXAM PLE1 id: type: string description: The unique identifier of the custom order (scheduled action ID). example: AEGXGV-JZ4I2-6QXEJS timestamp: type: string format: date-time description: The timestamp when the order was executed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' action: $ref: '#/components/schemas/CustomOrderTradeAction' trigger: $ref: '#/components/schemas/PriceTrigger' execution_details: $ref: '#/components/schemas/ExecutionDetails' description: > Runtime details captured from the underlying trade execution. Present when the upstream trade emits execution details for the occurrence; omitted otherwise. required: - event_type - iiban - id - timestamp - action - trigger ExecutionDetails: type: object description: | Runtime details captured from the executed trade. properties: quote_id: type: string description: >- The transaction identifier (quote ID) associated with the executed trade. example: BQEXAMP-LE123-ABCDEF spend: $ref: '#/components/schemas/AssetAmount' description: The spend-side asset and amount actually executed. receive: $ref: '#/components/schemas/AssetAmount' description: The receive-side asset and amount actually executed. total_fee: $ref: '#/components/schemas/AssetAmount' description: The total fee charged for the execution. unit_price: $ref: '#/components/schemas/AssetAmount' description: The unit price applied to the execution. executed_at: type: string format: date-time description: >- The timestamp when the upstream trade was executed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - quote_id CustomOrderFailedReason: type: object description: Reason for a custom order execution failure. properties: type: type: string description: The reason category. enum: - failed example: failed detail: type: string description: > The specific failure reason. Possible values: `system_error`, `insufficient_market_liquidity`, `insufficient_funds`, `card_processing_failure`, `trade_amount_too_small`, `trade_amount_too_large`, `user_locked`, `card_transaction_declined_by_issuer`, `user_temporarily_restricted`, `asset_coming_soon`, `withdrawal_amount_too_small`, `canadian_acquisition_limit_exceeded`, `withdrawal_amount_too_large`, `canadian_suitability_limit_exceeded`, `user_kyc_deny_trading`, `user_kyc_finprom_survey`, `user_kyc_finprom_assessment_locked`, `user_kyc_onboarding_cool_off`, `insufficient_margin`, `funding_rail_transaction_limit_exceeded`, `user_bundle_without_balance`, `retry_exhausted_unsatisfying_unit_price`. enum: - system_error - insufficient_market_liquidity - insufficient_funds - card_processing_failure - trade_amount_too_small - trade_amount_too_large - user_locked - card_transaction_declined_by_issuer - user_temporarily_restricted - asset_coming_soon - withdrawal_amount_too_small - canadian_acquisition_limit_exceeded - withdrawal_amount_too_large - canadian_suitability_limit_exceeded - user_kyc_deny_trading - user_kyc_finprom_survey - user_kyc_finprom_assessment_locked - user_kyc_onboarding_cool_off - insufficient_margin - funding_rail_transaction_limit_exceeded - user_bundle_without_balance - retry_exhausted_unsatisfying_unit_price example: insufficient_funds required: - type - detail CustomOrderExecutionFailedEvent: type: object description: > Sent when a custom order execution has failed. The price trigger condition was met, but the trade could not be completed. The `reason` field indicates why the execution failed. properties: event_type: type: string description: The event type identifier. enum: - custom_order.execution_failed example: custom_order.execution_failed iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose custom order execution failed. example: AA00 TEST EXAM PLE1 id: type: string description: The unique identifier of the custom order (scheduled action ID). example: AEGXGV-JZ4I2-6QXEJS reason: $ref: '#/components/schemas/CustomOrderFailedReason' timestamp: type: string format: date-time description: The timestamp when the execution failed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' action: $ref: '#/components/schemas/CustomOrderTradeAction' trigger: $ref: '#/components/schemas/PriceTrigger' required: - event_type - iiban - id - timestamp - action - trigger CustomOrderCancelledReason: type: object description: Reason for a custom order cancellation. properties: type: type: string description: The reason category. enum: - cancelled example: cancelled detail: type: string description: > The specific cancellation reason. Possible values: `user_request`, `user_locked`, `expired_payment_method`, `asset_unavailable`, `pair_unavailable`, `retries_exhausted`, `funding_method_deleted`, `user_bundle_dissolved`, `user_bundle_liquidated`, `no_balances_to_rebalance_bundle`, or an `other` variant with freeform details. example: user_request required: - type - detail CustomOrderCancelledEvent: type: object description: > Sent when a custom order was cancelled. This can happen when the user explicitly cancels the order, or when the system cancels it due to account restrictions, asset unavailability, or other conditions. properties: event_type: type: string description: The event type identifier. enum: - custom_order.cancelled example: custom_order.cancelled iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose custom order was cancelled. example: AA00 TEST EXAM PLE1 id: type: string description: The unique identifier of the custom order (scheduled action ID). example: AEGXGV-JZ4I2-6QXEJS reason: $ref: '#/components/schemas/CustomOrderCancelledReason' timestamp: type: string format: date-time description: The timestamp when the order was cancelled (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' action: $ref: '#/components/schemas/CustomOrderTradeAction' trigger: $ref: '#/components/schemas/PriceTrigger' required: - event_type - iiban - id - reason - timestamp - action - trigger QuoteExecutedEvent: type: object description: Sent when a quote has been successfully executed. properties: event_type: type: string description: The event type identifier. enum: - quote.executed example: quote.executed iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user who executed the quote. example: AA00 TEST EXAM PLE1 quote_id: type: string description: The unique identifier of the executed quote. example: BQEXAMP-LE123-ABCDEF timestamp: type: string format: date-time description: The timestamp when the quote was executed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - quote_id - timestamp QuoteExecutionFailedEvent: type: object description: Sent when a quote execution has failed. properties: event_type: type: string description: The event type identifier. enum: - quote.execution_failed example: quote.execution_failed iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose quote execution failed. example: AA00 TEST EXAM PLE1 quote_id: type: string description: The unique identifier of the failed quote. example: BQEXAMP-LE123-ABCDEF reason: type: string description: > A free-form, human-readable description of why the quote execution failed. This field is intended for display and logging purposes only. Clients should not rely on specific reason strings for programmatic decision-making, as the exact wording may change without notice. example: Insufficient funds timestamp: type: string format: date-time description: The timestamp when the quote execution failed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - quote_id - reason - timestamp QuoteCancelledEvent: type: object description: Sent when a quote was cancelled before execution. properties: event_type: type: string description: The event type identifier. enum: - quote.cancelled example: quote.cancelled iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose quote was cancelled. example: AA00 TEST EXAM PLE1 quote_id: type: string description: The unique identifier of the cancelled quote. example: BQEXAMP-LE123-ABCDEF reason: type: string description: > A free-form, human-readable description of why the quote was cancelled. This field is intended for display and logging purposes only. Clients should not rely on specific reason strings for programmatic decision-making, as the exact wording may change without notice. example: Quote expired timestamp: type: string format: date-time description: The timestamp when the quote was cancelled (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - quote_id - reason - timestamp DepositStatusUpdatedEvent: type: object description: > Sent when a deposit's status changes. The `event` field indicates the lifecycle sub-event: `received` (deposit detected on-chain), `held` (deposit under review), `credited` (funds available in the user's account), or `failed` (deposit rejected). properties: event_type: type: string description: The event type identifier. enum: - deposit.status_updated example: deposit.status_updated iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose deposit status changed. example: AA00 TEST EXAM PLE1 event: type: string description: | The deposit lifecycle sub-event that triggered this webhook. - `received` — deposit detected on-chain but not yet credited - `held` — deposit is under review (see `reason`) - `credited` — funds are now available in the user's account - `failed` — deposit was rejected (see `reason`) enum: - received - held - credited - failed example: credited reason: type: string description: > Human-readable reason for the status change. Present for `held` and `failed` events. This field is intended for display and logging purposes only. Clients should not rely on specific reason strings for programmatic decision-making, as the exact wording may change without notice. example: aml_check, manual_review amount: $ref: '#/components/schemas/AssetAmount' description: The deposit amount. Present for `credited` events. fee: $ref: '#/components/schemas/AssetAmount' description: The deposit fee. Present for `credited` events. transaction_id: type: string description: The unique identifier for the deposit transaction. example: TX62ZZF-ZYY4I-4QBAUW timestamp: type: string format: date-time description: The timestamp when the status changed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - event - transaction_id - timestamp WithdrawalStatusUpdatedEvent: type: object description: | Sent when a withdrawal's status changes. The `event` field is the lifecycle sub-event emitted by funding: - `received` — withdrawal request accepted and queued - `held` — withdrawal is held for review (see `reasons`) - `released` — withdrawal released from hold and processing resumes - `complete` — withdrawal completed successfully - `failed` — withdrawal failed (see `reasons` when provided) The `status` field is the partner-facing normalized status used across polling APIs (`in_progress`, `held`, `successful`, `failed`). properties: event_type: type: string description: The event type identifier. enum: - withdrawal.status_updated example: withdrawal.status_updated iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user whose withdrawal status changed. example: AA00 TEST EXAM PLE1 ref_id: type: string description: >- Encrypted funding transaction identifier. This matches `ref_id` returned by withdrawal APIs and transaction polling. example: FTT35sk-P9HoywSFWa1VTg1owfSs2n status: type: string description: Partner-facing normalized withdrawal status. enum: - in_progress - held - successful - failed example: in_progress event: type: string description: Withdrawal lifecycle sub-event. enum: - received - held - released - complete - failed example: received reasons: type: array description: Optional list of reasons associated with held/failed events. items: type: string example: - aml_check - manual_review timestamp: type: string format: date-time description: The timestamp when the status changed (ISO-8601 format). example: '2026-02-28T12:00:00.000000000Z' required: - event_type - iiban - ref_id - status - event - timestamp UserVerifiedEvent: type: object description: Sent when a user has been verified and can now trade on the platform. properties: event_type: type: string description: The event type identifier. enum: - user.verified example: user.verified iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the verified user. example: AA00 TEST EXAM PLE1 timestamp: type: string format: date-time description: The timestamp when the user was verified (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - timestamp UserClosedEvent: type: object description: >- Sent when a user's account has been permanently closed. The user can no longer perform any actions on the platform. properties: event_type: type: string description: The event type identifier. enum: - user.closed example: user.closed iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the closed user. example: AA00 TEST EXAM PLE1 timestamp: type: string format: date-time description: The timestamp when the account was closed (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - timestamp UserDisabledEvent: type: object description: > Sent when a user's account has been disabled. This can happen when the account is suspended, a trade lock is applied, or other restrictions are placed on the account. The user cannot trade while in this state. properties: event_type: type: string description: The event type identifier. enum: - user.disabled example: user.disabled iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the disabled user. example: AA00 TEST EXAM PLE1 timestamp: type: string format: date-time description: The timestamp when the account was disabled (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - timestamp RewardPaidEvent: type: object description: Sent when an Earn reward has been paid to a user. properties: event_type: type: string description: The event type identifier. enum: - reward.paid example: reward.paid iiban: type: string description: >- The Internet International Bank Account Number (IIBAN) of the user who received the reward. example: AA00 TEST EXAM PLE1 payout_id: type: string description: The unique identifier of the reward payout. example: '236191441' asset: type: string description: The asset that was paid out. example: ETH amount: type: string description: The amount of the reward payout. example: '0.0000076470' auto_compound: type: boolean description: Whether the reward is set to auto-compound. example: true timestamp: type: string format: date-time description: The timestamp when the reward was paid (ISO-8601 format). example: '2025-01-15T10:30:00.000000000Z' required: - event_type - iiban - payout_id - asset - amount - auto_compound - timestamp WebhookTestEvent: type: object description: Sent when testing a webhook configuration via the Test Webhook endpoint. properties: event_type: type: string description: The event type identifier. enum: - webhook.test example: webhook.test message: type: string description: A test message confirming the webhook is working. example: This is a test webhook event to verify your endpoint configuration. timestamp: type: string format: date-time description: The timestamp when the test webhook was sent (ISO-8601 format). example: '2025-01-15T10:30:00Z' test_id: type: string format: uuid description: >- Unique identifier for the test webhook. Use this to search logs for troubleshooting. example: 550e8400-e29b-41d4-a716-446655440000 required: - event_type - message - timestamp - test_id error: type: object properties: errors: type: array items: description: >- Error objects provide additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document. An error object MAY have the following members, and MUST contain at least one of: type: object properties: id: nullable: true description: >- A unique identifier for this particular occurrence of the problem. type: string links: nullable: true description: A links object that MAY contain `about` and `type` members. type: object properties: about: nullable: true description: >- A link that leads to further details about this particular occurrence of the problem. When dereferenced, this URI SHOULD return a human-readable description of the error. anyOf: - description: An RFC 3986 URI type: string - description: >- A "link object" is an object that represents a web link. Note: the `type` and `hreflang` members are only hints; the target resource is not guaranteed to be available in the indicated media type or language when the link is actually followed. type: object properties: href: description: >- A string whose value is a URI-reference [RFC3986 Section 4.1] pointing to the link's target. type: string rel: nullable: true description: >- A string indicating the link's relation type. The string MUST be a valid link relation type. anyOf: - type: string - description: An RFC 3986 URI type: string describedby: nullable: true description: >- A link to a description document (e.g. OpenAPI or JSON Schema) for the link target. type: string title: nullable: true description: >- A string which serves as a label for the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry). type: string type: nullable: true description: >- A string indicating the media type of the link's target. type: string hreflang: nullable: true description: >- A string or an array of strings indicating the language(s) of the link's target. An array of strings indicates that the link's target is available in multiple languages. Each string MUST be a valid language tag [RFC5646]. anyOf: - example: az-Arab-x-AZE-derbend title: RFC5646 Language Tag description: >- JSON Schema for validating RFC5646/BCP47 language tags type: string pattern: ^([a-zA-Z]{1,8})(-[a-zA-Z\d]{1,8})*$ - type: array items: example: az-Arab-x-AZE-derbend title: RFC5646 Language Tag description: >- JSON Schema for validating RFC5646/BCP47 language tags type: string pattern: ^([a-zA-Z]{1,8})(-[a-zA-Z\d]{1,8})*$ meta: nullable: true description: >- A meta object containing non-standard meta-information about the link. type: object required: - href - {} type: nullable: true description: >- A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferenceable to a human-readable explanation of the general error. anyOf: - description: An RFC 3986 URI type: string - description: >- A "link object" is an object that represents a web link. Note: the `type` and `hreflang` members are only hints; the target resource is not guaranteed to be available in the indicated media type or language when the link is actually followed. type: object properties: href: description: >- A string whose value is a URI-reference [RFC3986 Section 4.1] pointing to the link's target. type: string rel: nullable: true description: >- A string indicating the link's relation type. The string MUST be a valid link relation type. anyOf: - type: string - description: An RFC 3986 URI type: string describedby: nullable: true description: >- A link to a description document (e.g. OpenAPI or JSON Schema) for the link target. type: string title: nullable: true description: >- A string which serves as a label for the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry). type: string type: nullable: true description: >- A string indicating the media type of the link's target. type: string hreflang: nullable: true description: >- A string or an array of strings indicating the language(s) of the link's target. An array of strings indicates that the link's target is available in multiple languages. Each string MUST be a valid language tag [RFC5646]. anyOf: - example: az-Arab-x-AZE-derbend title: RFC5646 Language Tag description: >- JSON Schema for validating RFC5646/BCP47 language tags type: string pattern: ^([a-zA-Z]{1,8})(-[a-zA-Z\d]{1,8})*$ - type: array items: example: az-Arab-x-AZE-derbend title: RFC5646 Language Tag description: >- JSON Schema for validating RFC5646/BCP47 language tags type: string pattern: ^([a-zA-Z]{1,8})(-[a-zA-Z\d]{1,8})*$ meta: nullable: true description: >- A meta object containing non-standard meta-information about the link. type: object required: - href - {} status: nullable: true description: >- The HTTP status code applicable to this problem, expressed as a string value. This SHOULD be provided. type: string code: nullable: true description: >- An application-specific error code, expressed as a string value. type: string title: nullable: true description: >- A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. type: string detail: nullable: true description: >- A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized. type: string source: nullable: true description: >- An object containing references to the primary source of the error. oneOf: - description: >- A JSON Pointer [RFC6901] to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn't, the client SHOULD simply ignore the pointer. type: object properties: pointer: type: string required: - pointer - description: >- A string indicating which URI query parameter caused the error. type: object properties: parameter: type: string required: - parameter - description: >- A string indicating the name of a single request header which caused the error. type: object properties: header: type: string required: - header meta: nullable: true description: >- A meta object containing non-standard meta-information about the error. type: object