From 212bb21739c9ac47f7c5232f639b1957802a70e2 Mon Sep 17 00:00:00 2001 From: pablofelitti-paxos Date: Tue, 17 Feb 2026 13:12:37 -0300 Subject: [PATCH 1/3] AO-1017: Add PENDING_APPROVAL orchestration status to public documentation Add PENDING_APPROVAL to the orchestration status enum across all docs: OpenAPI specs, webhook definitions, state diagram, and event object docs. Also add the new orchestration.pending_approval webhook event for maker-checker approvals. Co-Authored-By: Claude Opus 4.6 --- .../orchestration-status-change-object.mdx | 4 +-- ...axos-v2-preview-orchestration.openapi.json | 1 + .../orchestration-pending-approval.mdx | 15 +++++++++ api-reference/webhooks/webhooks-openapi.json | 31 ++++++++++++++++++- docs.json | 1 + .../orchestrations/orchestrations.mdx | 7 ++++- 6 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 api-reference/webhooks/orchestration-pending-approval.mdx diff --git a/api-reference/events/orchestration-status-change-object.mdx b/api-reference/events/orchestration-status-change-object.mdx index 6a7576f1..5c29ebcc 100644 --- a/api-reference/events/orchestration-status-change-object.mdx +++ b/api-reference/events/orchestration-status-change-object.mdx @@ -3,7 +3,7 @@ title: "orchestration_status_change" description: "Event object returned for orchestration status change events" --- -This object is returned by the [Get Event API](/api-reference/endpoints/events/get-event) when the event type is `orchestration.processing`, `orchestration.completed`, or `orchestration.failed`. +This object is returned by the [Get Event API](/api-reference/endpoints/events/get-event) when the event type is `orchestration.pending_approval`, `orchestration.processing`, `orchestration.completed`, or `orchestration.failed`. ## Object Fields @@ -18,7 +18,7 @@ The client-specified ID of the orchestration for replay protection and lookup. Status of the orchestration: -**Available options:** `PROCESSING`, `COMPLETED`, `FAILED` +**Available options:** `PENDING_APPROVAL`, `PROCESSING`, `COMPLETED`, `FAILED` diff --git a/api-reference/preview/paxos-v2-preview-orchestration.openapi.json b/api-reference/preview/paxos-v2-preview-orchestration.openapi.json index b6a49b64..18c7f23e 100644 --- a/api-reference/preview/paxos-v2-preview-orchestration.openapi.json +++ b/api-reference/preview/paxos-v2-preview-orchestration.openapi.json @@ -612,6 +612,7 @@ "OrchestrationStatus": { "type": "string", "enum": [ + "PENDING_APPROVAL", "PROCESSING", "COMPLETED", "FAILED" diff --git a/api-reference/webhooks/orchestration-pending-approval.mdx b/api-reference/webhooks/orchestration-pending-approval.mdx new file mode 100644 index 00000000..7037837a --- /dev/null +++ b/api-reference/webhooks/orchestration-pending-approval.mdx @@ -0,0 +1,15 @@ +--- +title: "orchestration.pending_approval" +description: "Webhook triggered when an orchestration requires maker-checker approval" +openapi: "webhooks-openapi.json webhook orchestration.pending_approval" +--- + +Triggered when an ad-hoc orchestration requires maker-checker approval before processing can begin. + + +Webhook payloads contain only event metadata. Use the [Get Event API](/api-reference/endpoints/events/get-event) with the event ID to retrieve full details. + + +## Event Object Structure + +The Get Event API returns an [`orchestration_status_change`](/api-reference/events/orchestration-status-change-object) object with orchestration status details. diff --git a/api-reference/webhooks/webhooks-openapi.json b/api-reference/webhooks/webhooks-openapi.json index c9585f59..b57042e4 100644 --- a/api-reference/webhooks/webhooks-openapi.json +++ b/api-reference/webhooks/webhooks-openapi.json @@ -207,6 +207,34 @@ "description": "Triggered when a KYC refresh process expires without completion. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details." } }, + "orchestration.pending_approval": { + "post": { + "requestBody": { + "description": "Webhook payload containing event metadata. Use the event ID with the Get Event API to retrieve full details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookEvent" + }, + "example": { + "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41", + "type": "orchestration.pending_approval", + "source": "com.paxos", + "time": "2025-01-07T14:30:02Z", + "object": "event" + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully received" + } + }, + "summary": "Orchestration Pending Approval", + "description": "Triggered when an ad-hoc orchestration requires maker-checker approval before processing can begin. Your endpoint should respond with a 2xx status code to acknowledge receipt. Use the event ID to call the Get Event API for full details." + } + }, "orchestration.processing": { "post": { "requestBody": { @@ -1577,6 +1605,7 @@ "identity.kyc_refresh.started", "identity.kyc_refresh.completed", "identity.kyc_refresh.expired", + "orchestration.pending_approval", "orchestration.processing", "orchestration.completed", "orchestration.failed", @@ -1764,7 +1793,7 @@ }, "status": { "type": "string", - "enum": ["PROCESSING", "COMPLETED", "FAILED"], + "enum": ["PENDING_APPROVAL", "PROCESSING", "COMPLETED", "FAILED"], "title": "Orchestration Status", "description": "Status of the orchestration" } diff --git a/docs.json b/docs.json index e84d0dcc..2f5e0851 100644 --- a/docs.json +++ b/docs.json @@ -938,6 +938,7 @@ { "group": "Hooks", "pages": [ + "api-reference/webhooks/orchestration-pending-approval", "api-reference/webhooks/orchestration-processing", "api-reference/webhooks/orchestration-completed", "api-reference/webhooks/orchestration-failed" diff --git a/guides/developer/orchestrations/orchestrations.mdx b/guides/developer/orchestrations/orchestrations.mdx index a00b367c..4d3fc9bb 100644 --- a/guides/developer/orchestrations/orchestrations.mdx +++ b/guides/developer/orchestrations/orchestrations.mdx @@ -120,19 +120,24 @@ To use orchestrations, you'll need the following OAuth scopes when [authenticati ## Monitoring Orchestration Status -Orchestrations can exist in three states. To monitor them there's a few options. +Orchestrations can exist in four states. To monitor them there's a few options.
```mermaid stateDiagram-v2 + [*] --> PENDING_APPROVAL: Approval Required [*] --> PROCESSING: Orchestration Created + PENDING_APPROVAL --> PROCESSING: Approved + PENDING_APPROVAL --> FAILED: Rejected PROCESSING --> COMPLETED: Success PROCESSING --> FAILED: Error ```
+Ad-hoc orchestrations that require maker-checker approval enter the `PENDING_APPROVAL` state before processing begins. Once approved, they transition to `PROCESSING`. If rejected, they transition directly to `FAILED`. + ### Recommended: Using Webhooks > Subscribe to orchestration webhooks for real-time status monitoring. This is the recommended approach as it provides immediate notifications without polling. From abde19a136097122118d2d90b79551f24f3beb0c Mon Sep 17 00:00:00 2001 From: pablofelitti-paxos Date: Fri, 13 Mar 2026 15:22:40 -0300 Subject: [PATCH 2/3] Remove Settlements API documentation Remove all settlement-related guide pages, API reference pages, and navigation entries from docs.json, including the /settlements/:slug* redirect. Co-Authored-By: Claude Sonnet 4.6 --- .../settlement/affirm-transaction.mdx | 7 - .../settlement/cancel-transaction.mdx | 7 - .../settlement/create-transaction.mdx | 7 - .../endpoints/settlement/get-transaction.mdx | 7 - .../settlement/list-transactions.mdx | 7 - .../endpoints/settlement/overview.mdx | 19 - docs.json | 30 -- guides/settlements/faq.mdx | 30 -- guides/settlements/index.mdx | 44 --- guides/settlements/notification.mdx | 15 - guides/settlements/quickstart.mdx | 333 ------------------ guides/settlements/status.mdx | 126 ------- guides/settlements/triparty.mdx | 4 - 13 files changed, 636 deletions(-) delete mode 100644 api-reference/endpoints/settlement/affirm-transaction.mdx delete mode 100644 api-reference/endpoints/settlement/cancel-transaction.mdx delete mode 100644 api-reference/endpoints/settlement/create-transaction.mdx delete mode 100644 api-reference/endpoints/settlement/get-transaction.mdx delete mode 100644 api-reference/endpoints/settlement/list-transactions.mdx delete mode 100644 api-reference/endpoints/settlement/overview.mdx delete mode 100644 guides/settlements/faq.mdx delete mode 100644 guides/settlements/index.mdx delete mode 100644 guides/settlements/notification.mdx delete mode 100644 guides/settlements/quickstart.mdx delete mode 100644 guides/settlements/status.mdx delete mode 100644 guides/settlements/triparty.mdx diff --git a/api-reference/endpoints/settlement/affirm-transaction.mdx b/api-reference/endpoints/settlement/affirm-transaction.mdx deleted file mode 100644 index 0bb32f3a..00000000 --- a/api-reference/endpoints/settlement/affirm-transaction.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: put /settlement/transactions/{transaction_id}/affirm ---- - -```bash OAuth Scope -settlement:write_transaction -``` diff --git a/api-reference/endpoints/settlement/cancel-transaction.mdx b/api-reference/endpoints/settlement/cancel-transaction.mdx deleted file mode 100644 index c7582a1c..00000000 --- a/api-reference/endpoints/settlement/cancel-transaction.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: delete /settlement/transactions/{transaction_id} ---- - -```bash OAuth Scope -settlement:write_transaction -``` diff --git a/api-reference/endpoints/settlement/create-transaction.mdx b/api-reference/endpoints/settlement/create-transaction.mdx deleted file mode 100644 index 3084903d..00000000 --- a/api-reference/endpoints/settlement/create-transaction.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: post /settlement/transactions ---- - -```bash OAuth Scope -settlement:write_transaction -``` diff --git a/api-reference/endpoints/settlement/get-transaction.mdx b/api-reference/endpoints/settlement/get-transaction.mdx deleted file mode 100644 index 93422844..00000000 --- a/api-reference/endpoints/settlement/get-transaction.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: get /settlement/transactions/{transaction_id} ---- - -```bash OAuth Scope -settlement:read_transaction -``` diff --git a/api-reference/endpoints/settlement/list-transactions.mdx b/api-reference/endpoints/settlement/list-transactions.mdx deleted file mode 100644 index b2311809..00000000 --- a/api-reference/endpoints/settlement/list-transactions.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -openapi: get /settlement/transactions ---- - -```bash OAuth Scope -settlement:read_transaction -``` diff --git a/api-reference/endpoints/settlement/overview.mdx b/api-reference/endpoints/settlement/overview.mdx deleted file mode 100644 index 0343e26a..00000000 --- a/api-reference/endpoints/settlement/overview.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Overview" -description: "Use the Settlements API to facilitate simultaneous exchange of pre-funded assets." ---- - -Use the Settlements API to facilitate simultaneous exchange of pre-funded assets. Automate a variety of use cases that require two-party approval, including net settlement of over-the-counter trades, withdrawal requests for tri-party collateral, payment requests, and bilateral settlement for marketplace end users. - -## Workflow - -The simple request-and-approval workflow supports both one-directional and bidirectional transactions to allow a user to receive an asset (for example, send USDP) or simultaneously send and receive assets (for example, send USD and receive BTC and ETH). Only when all parties are in agreement and assets are fully funded does the Settlements API allow for change of custody. Upon completion, all settled assets are immediately available for trading, transferring, withdrawal or other supported activities. - -## Transaction Direction - -The Source Profile initiates the transaction for the Target Profile to approve. The `DIRECTION` of each asset is always relative to the Source Profile and only the owner of the Source Profile can cancel a transaction if it hasn't been approved by the Target Profile. - -## Learn More - -Learn more about the Settlement APIs in the [Settlement Developer Guide](/guides/settlements). - diff --git a/docs.json b/docs.json index 2f5e0851..c2765e22 100644 --- a/docs.json +++ b/docs.json @@ -65,10 +65,6 @@ "source": "/crypto-brokerage/:slug*", "destination": "/guides/crypto-brokerage/:slug*" }, - { - "source": "/settlements/:slug*", - "destination": "/guides/settlements/:slug*" - }, { "source": "/payments/:slug*", "destination": "/guides/payments/:slug*" @@ -187,16 +183,6 @@ "guides/payments/faq" ] }, - { - "group": "Settlements", - "pages": [ - "guides/settlements/index", - "guides/settlements/quickstart", - "guides/settlements/status", - "guides/settlements/notification", - "guides/settlements/faq" - ] - }, { "group": "Crypto Brokerage", "pages": [ @@ -585,22 +571,6 @@ } ] }, - { - "group": "Settlements", - "pages": [ - { - "group": "Settlement", - "pages": [ - "api-reference/endpoints/settlement/overview", - "api-reference/endpoints/settlement/list-transactions", - "api-reference/endpoints/settlement/create-transaction", - "api-reference/endpoints/settlement/get-transaction", - "api-reference/endpoints/settlement/cancel-transaction", - "api-reference/endpoints/settlement/affirm-transaction" - ] - } - ] - }, { "group": "Orchestrations / Conversions", "pages": [ diff --git a/guides/settlements/faq.mdx b/guides/settlements/faq.mdx deleted file mode 100644 index 600fab20..00000000 --- a/guides/settlements/faq.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'FAQ' -description: Get answers to common questions about the Settlements API. ---- - - - - - - -No. -You can create and approve the transaction first and then deposit [assets](/guides/developer/blockchains) when ready. -Settlement only takes place when the transaction is [affirmed](/guides/settlements/status) and all the required assets have been deposited. - - - - - -Notifications are off by default in Sandbox. Contact [Support](https://support.paxos.com) to turn them on. - - - - - -You can fund your Sandbox Account with the supported [assets](/guides/developer/blockchains) or those listed in [Create Sandbox Deposit](/api-reference/endpoints/sandbox-deposits/create-sandbox-deposit). -For most setups, use the assets you can trade, transfer or withdraw for testing. - - - - diff --git a/guides/settlements/index.mdx b/guides/settlements/index.mdx deleted file mode 100644 index ec1ad39e..00000000 --- a/guides/settlements/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: 'Overview' -description: Propose, approve and manage two-way atomic transfers. ---- - - -![Settlements Profiles](/images/settlement-profiles.png) - -Use the Settlements API to facilitate simultaneous exchange of pre-funded assets. -Automate a variety of use cases that require two-party approval, including -net settlement of over-the-counter trades, withdrawal requests for tri-party collateral, payment requests, and bilateral settlement for marketplace end users. - -The simple request-and-approval workflow supports both one-directional and bidirectional transactions to allow a user to receive an asset (for example, send USDP) or simultaneously send and receive assets (for example, send USD and receive BTC and ETH). -Only when all parties are in agreement and assets are fully funded does the Settlements API allow for change of custody. -Upon completion, all settled assets are immediately available for trading, transferring, withdrawal or other supported activities. - -## Settlement Workflow - -The settlement workflow requires two parties to complete: The Source Profile owner who [initiates](/api-reference/endpoints/settlement/create-transaction) the transaction and the Target Profile owner who [approves](/api-reference/endpoints/settlement/affirm-transaction) the transaction. -Most integrations follow a similar workflow: - -1. Both parties agree on the transaction details and share counterparty Profile IDs outside of the Paxos Platform (for example, via email, Telegram, or other application). -1. The Source Profile owner [submits the transaction](/api-reference/endpoints/settlement/create-transaction) to the settlement platform. -1. The Target Profile owner receives a [notification](/guides/settlements/notification), reviews the transaction details and [approves the transaction](/api-reference/endpoints/settlement/affirm-transaction). -1. Both parties fund the associated Profiles via deposits if the requisite balances are not already present. -1. Settlement (movement of assets between Profiles) occurs soon after both parties have sufficient assets on the platform. -1. Once the transaction [settles](/guides/settlements/status), both parties can immediately utilize the new balance. - -## Get Started - - - - Set up and complete the settlement workflow in the Sandbox environment. - - - Learn more about settlement statuses. - - - Understand how settlement notifications work. - - - Get answers to common questions about the Settlements API. - - diff --git a/guides/settlements/notification.mdx b/guides/settlements/notification.mdx deleted file mode 100644 index 831416a1..00000000 --- a/guides/settlements/notification.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Notifications' -description: Understand how settlement notifications work. ---- - - -By default, each Profile owner receives an email notification when a settlement transaction is [created](/api-reference/endpoints/settlement/create-transaction) and upon each [status](/guides/settlements/status) change. -Currently, only email notifications are supported. -Websocket and desktop notifications are being considered for future releases. - -> To test email notifications in Sandbox, contact [Support](https://support.paxos.com) to enable notifications. - -All settlement email notifications use the same template: - -![Settlements Email Notification](/images/settlement-notification.png) diff --git a/guides/settlements/quickstart.mdx b/guides/settlements/quickstart.mdx deleted file mode 100644 index 1da57935..00000000 --- a/guides/settlements/quickstart.mdx +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: 'Quickstart' -description: Set up and complete the settlement workflow in the Sandbox environment. ---- - - -The [settlement workflow](/guides/settlements#workflow) requires [two Profiles](#set-up-profiles), referred to in this guide as Source Profile (`source_profile_id`) and Target Profile (`target_profile_id`). -The Profiles are under the same Sandbox Account for simplicity and to allow completion of the steps with a single [authentication](#authenticate). -This guild also [funds](#fund) the Source Profile with BTC and ETH for the `DELIVER` leg and USD in the Target Profile for the `RECEIVE` leg before [creating the transaction request](#propose). - -> Contact your [Entity Manager](/guides/dashboard/roles#entity-manager) or [Support](https://support.paxos.com) if you run into any issues or don't have access to a Sandbox Account. - -## 1. Authenticate - -Add the `settlement:read_transaction` and `settlement:write_transaction` scopes to your [Sandbox Account](https://dashboard.sandbox.paxos.com) under the [API Management](https://dashboard.sandbox.paxos.com/admin/api) setting and then authenticate in Sandbox using the scopes. -Also include `funding:read_profile` and `funding:write_profile` for creating and funding [Profiles](/api-reference/endpoints/profiles). - -```shell highlight={5} -curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \ ---form grant_type=client_credentials \ ---form client_id={paxos_client_id} \ ---form client_secret={paxos_secret} \ ---form scope='settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile' -``` - -Confirm the response includes requisite scopes and save the `access_token` to use in the request authorization header throughout this guide. - -```json highlight={3,4} -{ - "access_token": "{access_token}", - "expires_in": 3599, // Seconds (59 Minutes and 59 Seconds) - "scope": "settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile", - "token_type": "bearer" -} -``` - -## 2. Set Up Profiles - -[Create](/api-reference/endpoints/profiles/create-profile) two new Profiles in the Sandbox Account, one with `Source Profile` and the second with `Target Profile` as the `nickname`. - -### Create Source Profile - -```shell highlight={4} -curl --location 'https://api.sandbox.paxos.com/v2/profiles' \ ---header 'Authorization: Bearer {access_token}' \ ---data '{ - "nickname": "Source Profile" -}' -``` - -You will need the `id` from the response to [fund the Profile](#fund) and [propose a transaction](#propose). - -```json highlight={2} -{ - "id": "{profile_id}", // The source_profile_id in the Transaction object - "nickname": "Source Profile", - "type": "NORMAL" -} -``` -### Create Target Profile - -```shell highlight={4} -curl --location 'https://api.sandbox.paxos.com/v2/profiles' \ ---header 'Authorization: Bearer {access_token}' \ ---data '{ - "nickname": "Target Profile" -}' -``` - -You will need the `id` from the response to [fund the Profile](#fund) and [propose a transaction](#propose). - -```json highlight={2} -{ - "id": "{profile_id}", // The target_profile_id in the Transaction object - "nickname": "Target Profile", - "type": "NORMAL" -} -``` -## 3. Fund Profiles - -Next, use [Create Sandbox Deposit](/api-reference/endpoints/sandbox-deposits/create-sandbox-deposit) to fund the Profiles. - - - -This guide pre-funds all accounts prior to [creating a settlement request](#propose) for simplicity. -However, it is possible to create and approve a settlement request [before the funds are available](/guides/settlements/faq#assets). - - -### Fund Source Profile - -Deposit crypto into the Source Profile. -First, Bitcoin: - -```shell -curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ ---header 'Authorization: Bearer {access_token}' \ ---data ' - { - "asset": "BTC", - "amount": "2", - "crypto_network": "BITCOIN" - }' - ``` - Then add some Ethereum: - - ```shell -curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ ---header 'Authorization: Bearer {access_token}' \ ---data ' - { - "asset": "ETH", - "amount": "10", - "crypto_network": "ETHEREUM" - }' - ``` -Use [List Profile Balances](/api-reference/endpoints/profiles/list-profile-balances) to retrieve the Source Profile balance. -Include the `assets` query parameter to filter out all other assets. - -```shell -curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances?assets=BTC&assets=ETH' \ ---header 'Authorization: Bearer {access_token}' -``` -Confirm the Source Profile has at least 1 BTC and 5 ETH available for trading. - -```json highlight={5,10} -{ - "items": [ - { - "asset": "BTC", - "available": "2", - "trading": "0" - }, - { - "asset": "ETH", - "available": "10", - "trading": "0" - } - ] -} -``` -### Fund Target Profile - -Deposit USD into the Target Profile. -```shell -curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ ---header 'Authorization: Bearer {access_token}' \ ---data ' - { - "asset": "USD", - "amount": "100000" - }' -``` - -Use [Get Profile Balance](/api-reference/endpoints/profiles/get-profile-balance) to retrieve the Target Profile USD balance. - -```shell -curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances/USD' \ ---header 'Authorization: Bearer {access_token}' -``` - -Confirm the Target Profile has at least $50,000 USD available for trading. - -```json highlight={3} -{ - "asset": "USD", - "available": "100000", - "trading": "0" -} -``` -## 4. Propose Transaction - -Using the Source Profile and Target Profile `profile_id` [created earlier](#set-up-profiles), use [Create Transaction](/api-reference/endpoints/settlement/create-transaction) to propose exchanging 1 BTC and 5 ETH (in the Source Profile balance) for $50,000 USD (in the Target Profile balance). The `ref_id` must be unique. The settlement window defaults apply if `settlement_window_start` and/or `settlement_window_end` are not specified. - -```shell highlight={4,5,6} -curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions' \ ---header 'Authorization: Bearer {access_token}' \ ---data '{ - "ref_id": "required_idempotence_id", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "legs": [ - { - "direction": "DELIVER", - "asset": "BTC", - "amount": "1.00" - }, - { - "direction": "DELIVER", - "asset": "ETH", - "amount": "5" - }, - { - "direction": "RECEIVE", - "asset": "USD", - "amount": "50000.00" - } - ] -}' -``` - -The acknowledgement response confirms the request has been received and provides the `Transaction` object. -The unique transaction `id` is used to [approve](#approve) and [retrieve](#check-status) the transaction, and the Source Profile owner can use the `id` to [cancel](/api-reference/endpoints/settlement/cancel-transaction) the `PENDING` transaction. -The transaction [status](/guides/settlements/status) can be used by either party to [retrieve a list of filtered transactions](/guides/settlements/status#list-transactions). - -```json highlight={2,28} -{ - "id": "{unique_transaction_id}", - "ref_id": "required_idempotence_id", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", // Defaults to current time - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", // Defaults to settlement_window_start plus 24 hours - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "legs": [ - { - "id": "{unique_leg_1_id}", - "direction": "DELIVER", // From Source Profile - "asset": "BTC", - "amount": "1" - }, - { - "id": "{unique_leg_2_id}", - "direction": "DELIVER", // From Source Profile - "asset": "ETH", - "amount": "5" - }, - { - "id": "{unique_leg_3_id}", - "direction": "RECEIVE", // From Target Profile - "asset": "USD", - "amount": "50000" - } - ], - "status": "PENDING", - "created_at": "YYYY-MM-DDT00:00:00Z", - "updated_at": "YYYY-MM-DDT00:00:00Z" -} -``` - -## 5. Approve Transaction - -The Target Profile owner [approves (affirms)](/api-reference/endpoints/settlement/affirm-transaction) the transaction. - - - -Since the same Paxos Account is used for both counterparty Profiles in this guide, you can use the same [authentication](#authenticate). - - - -Use the `Transaction.id` from the [propose step](#propose) as the `transaction_id`. -You can also [look up a transaction by status](/guides/settlements/status#list-transactions) to find the `id`. - -```shell -curl --location --request PUT 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}/affirm' \ ---header 'Authorization: Bearer {access_token}' -``` - -The acknowledgement response includes transaction information and the `AFFIRMED` [status](/guides/settlements/status) and `updated_at` timestamp. - -```json highlight={8,10} -{ - "id": "{unique_transaction_id}", - "ref_id": "required_idempotence_id", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "status": "AFFIRMED", - "created_at": "YYYY-MM-DDT00:00:00Z", - "updated_at": "YYYY-MM-DDT00:00:00Z" -} -``` - -## 6. Check Transaction Status - -Settlement of the `AFFIRMED` transaction occurs only when both counterparties fully fund their Profiles. - - - -Since both Profiles in this guide are [pre-funded](#set-up-profiles), the transaction settled within a few seconds. - - - -Either party can use [Get Transaction](/api-reference/endpoints/settlement/get-transaction) to check the [status](/guides/settlements/status). - -```shell -curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}' \ ---header 'Authorization: Bearer {access_token}' -``` - -The response includes the complete `Transaction` object. -When the transaction completes, the [status](/guides/settlements/status) and `updated_at` timestamp reflect the most recent activity. - -```json highlight={28,30} -{ - "id": "{unique_transaction_id}", - "ref_id": "required_idempotence_id", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "legs": [ - { - "id": "{unique_leg_1_id}", - "direction": "DELIVER", - "asset": "BTC", - "amount": "1" - }, - { - "id": "{unique_leg_2_id}", - "direction": "DELIVER", - "asset": "ETH", - "amount": "5" - }, - { - "id": "{unique_leg_3_id}", - "direction": "RECEIVE", - "asset": "USD", - "amount": "50000" - } - ], - "status": "SETTLED", - "created_at": "YYYY-MM-DDT00:00:00Z", - "updated_at": "YYYY-MM-DDT00:00:00Z" -} -``` - -## Next Steps - -- Create a settlement transaction before funding the Profiles. -- Learn more in the Settlements [FAQ](/guides/settlements/faq). -- Explore settlement methods and objects in the [Settlements API](/api-reference/endpoints/settlement). diff --git a/guides/settlements/status.mdx b/guides/settlements/status.mdx deleted file mode 100644 index 6229d89a..00000000 --- a/guides/settlements/status.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: 'Statuses' -description: Learn more about settlement statuses. ---- - - -The [settlement workflow](/guides/settlements/index#workflow) includes five statuses: - -- `PENDING`: Initial state of a settlement transaction upon creation by the Source Profile owner (`source_profile_id`). -- `AFFIRMED`: The settlement transaction has been approved by the Target Profile owner (`target_profile_id`) and will be eligible for settlement once within the transaction window (`settlement_window_start` → `settlement_window_end`). -- `SETTLED`: The assets in the transaction have successfully been transferred. -- `EXPIRED`: The settlement transaction is no longer eligible for settlement. -- `CANCELED`: The settlement transaction was canceled by the Source Profile owner. - -When a settlement transactions is [created](/api-reference/endpoints/settlement/create-transaction), it starts in `PENDING` status. -The assets do not need to be available in the Profiles at this stage. -In the `PENDING` state, two actions can be taken: -- The Source Profile owner [cancels](/api-reference/endpoints/settlement/cancel-transaction) the transaction. Status transitions to `CANCELLED`. -- The Target Profile owner [approves](/api-reference/endpoints/settlement/affirm-transaction) the transaction. Status transitions to `AFFIRMED`. - -Once the required asset balances are in the respective Profiles, settlement occurs. Status transactions to `SETTLED` when complete. - -```mermaid -flowchart LR - A[PENDING] ==> | Target Profile owner approves | B[AFFIRMED] ==>C[SETTLED] - A --> | Settlement window expires | D[EXPIRED] - A --> | Source Profile owner cancels | E[CANCELLED] - B --> D -``` - -Transactions in the `PENDING` or `AFFIRMED` state at the end of the settlement window (`settlement_window_end`) automatically transition to `EXPIRED`. - -## Find Transactions by Status - -Either involved party can use [List Transactions](/api-reference/endpoints/settlement/list-transactions) to retrieve all the transactions they are counterparty to. -Use the `statuses` query parameter to filter based on status. - - - -You must specify the `limit` of items per page or an error returns. - - - -```shell -curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?statuses=PENDING&statuses=AFFIRMED&limit=2' \ ---header 'Authorization: Bearer {access_token}' -``` - -Based on the request parameters, the response contains the two most recent open transactions. - -```json highlight={30,61,66} -{ - "items": [ - { - "id": "{unique_transaction_id}", - "ref_id": "required_idempotence_id_1", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "legs": [ - { - "id": "{unique_leg_1_id}", - "direction": "DELIVER", - "asset": "BTC", - "amount": "1" - }, - { - "id": "{unique_leg_2_id}", - "direction": "DELIVER", - "asset": "ETH", - "amount": "5" - }, - { - "id": "{unique_leg_3_id}", - "direction": "RECEIVE", - "asset": "USD", - "amount": "40000" - } - ], - "status": "PENDING", - "created_at": "YYYY-MM-DDT00:00:00Z", - "updated_at": "YYYY-MM-DDT00:00:00Z" - }, - { - "id": "{unique_transaction_id}", - "ref_id": "required_idempotence_id", - "settlement_window_start": "YYYY-MM-DDT00:00:00Z", - "settlement_window_end": "YYYY-MM-DDT00:00:00Z", - "source_profile_id": "{profile_id}", - "target_profile_id": "{profile_id}", - "legs": [ - { - "id": "{unique_leg_1_id}", - "direction": "DELIVER", - "asset": "BTC", - "amount": "1" - }, - { - "id": "{unique_leg_2_id}", - "direction": "DELIVER", - "asset": "ETH", - "amount": "5" - }, - { - "id": "{unique_leg_3_id}", - "direction": "RECEIVE", - "asset": "USD", - "amount": "40000" - } - ], - "status": "AFFIRMED", - "created_at": "YYYY-MM-DDT00:00:00Z", - "updated_at": "YYYY-MM-DDT00:00:00Z" - } - ], - "next_page_cursor": "{page_cursor_value}" -} -``` - -To view more items, add the `page_cursor` query parameter to the request. - -```shell highlight={1} -curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?limit=2&page_cursor={page_cursor_value}' \ ---header 'Authorization: Bearer {access_token}' -``` diff --git a/guides/settlements/triparty.mdx b/guides/settlements/triparty.mdx deleted file mode 100644 index 77a3b599..00000000 --- a/guides/settlements/triparty.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Triparty Collateral Management' -description: Using the Settlements API for triparty collateral management. ---- From f97806ce823b0dedd7c49ec8f76000dd69d15de8 Mon Sep 17 00:00:00 2001 From: pablofelitti-paxos Date: Fri, 13 Mar 2026 15:25:34 -0300 Subject: [PATCH 3/3] Revert "Remove Settlements API documentation" This reverts commit abde19a136097122118d2d90b79551f24f3beb0c. --- .../settlement/affirm-transaction.mdx | 7 + .../settlement/cancel-transaction.mdx | 7 + .../settlement/create-transaction.mdx | 7 + .../endpoints/settlement/get-transaction.mdx | 7 + .../settlement/list-transactions.mdx | 7 + .../endpoints/settlement/overview.mdx | 19 + docs.json | 30 ++ guides/settlements/faq.mdx | 30 ++ guides/settlements/index.mdx | 44 +++ guides/settlements/notification.mdx | 15 + guides/settlements/quickstart.mdx | 333 ++++++++++++++++++ guides/settlements/status.mdx | 126 +++++++ guides/settlements/triparty.mdx | 4 + 13 files changed, 636 insertions(+) create mode 100644 api-reference/endpoints/settlement/affirm-transaction.mdx create mode 100644 api-reference/endpoints/settlement/cancel-transaction.mdx create mode 100644 api-reference/endpoints/settlement/create-transaction.mdx create mode 100644 api-reference/endpoints/settlement/get-transaction.mdx create mode 100644 api-reference/endpoints/settlement/list-transactions.mdx create mode 100644 api-reference/endpoints/settlement/overview.mdx create mode 100644 guides/settlements/faq.mdx create mode 100644 guides/settlements/index.mdx create mode 100644 guides/settlements/notification.mdx create mode 100644 guides/settlements/quickstart.mdx create mode 100644 guides/settlements/status.mdx create mode 100644 guides/settlements/triparty.mdx diff --git a/api-reference/endpoints/settlement/affirm-transaction.mdx b/api-reference/endpoints/settlement/affirm-transaction.mdx new file mode 100644 index 00000000..0bb32f3a --- /dev/null +++ b/api-reference/endpoints/settlement/affirm-transaction.mdx @@ -0,0 +1,7 @@ +--- +openapi: put /settlement/transactions/{transaction_id}/affirm +--- + +```bash OAuth Scope +settlement:write_transaction +``` diff --git a/api-reference/endpoints/settlement/cancel-transaction.mdx b/api-reference/endpoints/settlement/cancel-transaction.mdx new file mode 100644 index 00000000..c7582a1c --- /dev/null +++ b/api-reference/endpoints/settlement/cancel-transaction.mdx @@ -0,0 +1,7 @@ +--- +openapi: delete /settlement/transactions/{transaction_id} +--- + +```bash OAuth Scope +settlement:write_transaction +``` diff --git a/api-reference/endpoints/settlement/create-transaction.mdx b/api-reference/endpoints/settlement/create-transaction.mdx new file mode 100644 index 00000000..3084903d --- /dev/null +++ b/api-reference/endpoints/settlement/create-transaction.mdx @@ -0,0 +1,7 @@ +--- +openapi: post /settlement/transactions +--- + +```bash OAuth Scope +settlement:write_transaction +``` diff --git a/api-reference/endpoints/settlement/get-transaction.mdx b/api-reference/endpoints/settlement/get-transaction.mdx new file mode 100644 index 00000000..93422844 --- /dev/null +++ b/api-reference/endpoints/settlement/get-transaction.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /settlement/transactions/{transaction_id} +--- + +```bash OAuth Scope +settlement:read_transaction +``` diff --git a/api-reference/endpoints/settlement/list-transactions.mdx b/api-reference/endpoints/settlement/list-transactions.mdx new file mode 100644 index 00000000..b2311809 --- /dev/null +++ b/api-reference/endpoints/settlement/list-transactions.mdx @@ -0,0 +1,7 @@ +--- +openapi: get /settlement/transactions +--- + +```bash OAuth Scope +settlement:read_transaction +``` diff --git a/api-reference/endpoints/settlement/overview.mdx b/api-reference/endpoints/settlement/overview.mdx new file mode 100644 index 00000000..0343e26a --- /dev/null +++ b/api-reference/endpoints/settlement/overview.mdx @@ -0,0 +1,19 @@ +--- +title: "Overview" +description: "Use the Settlements API to facilitate simultaneous exchange of pre-funded assets." +--- + +Use the Settlements API to facilitate simultaneous exchange of pre-funded assets. Automate a variety of use cases that require two-party approval, including net settlement of over-the-counter trades, withdrawal requests for tri-party collateral, payment requests, and bilateral settlement for marketplace end users. + +## Workflow + +The simple request-and-approval workflow supports both one-directional and bidirectional transactions to allow a user to receive an asset (for example, send USDP) or simultaneously send and receive assets (for example, send USD and receive BTC and ETH). Only when all parties are in agreement and assets are fully funded does the Settlements API allow for change of custody. Upon completion, all settled assets are immediately available for trading, transferring, withdrawal or other supported activities. + +## Transaction Direction + +The Source Profile initiates the transaction for the Target Profile to approve. The `DIRECTION` of each asset is always relative to the Source Profile and only the owner of the Source Profile can cancel a transaction if it hasn't been approved by the Target Profile. + +## Learn More + +Learn more about the Settlement APIs in the [Settlement Developer Guide](/guides/settlements). + diff --git a/docs.json b/docs.json index c2765e22..2f5e0851 100644 --- a/docs.json +++ b/docs.json @@ -65,6 +65,10 @@ "source": "/crypto-brokerage/:slug*", "destination": "/guides/crypto-brokerage/:slug*" }, + { + "source": "/settlements/:slug*", + "destination": "/guides/settlements/:slug*" + }, { "source": "/payments/:slug*", "destination": "/guides/payments/:slug*" @@ -183,6 +187,16 @@ "guides/payments/faq" ] }, + { + "group": "Settlements", + "pages": [ + "guides/settlements/index", + "guides/settlements/quickstart", + "guides/settlements/status", + "guides/settlements/notification", + "guides/settlements/faq" + ] + }, { "group": "Crypto Brokerage", "pages": [ @@ -571,6 +585,22 @@ } ] }, + { + "group": "Settlements", + "pages": [ + { + "group": "Settlement", + "pages": [ + "api-reference/endpoints/settlement/overview", + "api-reference/endpoints/settlement/list-transactions", + "api-reference/endpoints/settlement/create-transaction", + "api-reference/endpoints/settlement/get-transaction", + "api-reference/endpoints/settlement/cancel-transaction", + "api-reference/endpoints/settlement/affirm-transaction" + ] + } + ] + }, { "group": "Orchestrations / Conversions", "pages": [ diff --git a/guides/settlements/faq.mdx b/guides/settlements/faq.mdx new file mode 100644 index 00000000..600fab20 --- /dev/null +++ b/guides/settlements/faq.mdx @@ -0,0 +1,30 @@ +--- +title: 'FAQ' +description: Get answers to common questions about the Settlements API. +--- + + + + + + +No. +You can create and approve the transaction first and then deposit [assets](/guides/developer/blockchains) when ready. +Settlement only takes place when the transaction is [affirmed](/guides/settlements/status) and all the required assets have been deposited. + + + + + +Notifications are off by default in Sandbox. Contact [Support](https://support.paxos.com) to turn them on. + + + + + +You can fund your Sandbox Account with the supported [assets](/guides/developer/blockchains) or those listed in [Create Sandbox Deposit](/api-reference/endpoints/sandbox-deposits/create-sandbox-deposit). +For most setups, use the assets you can trade, transfer or withdraw for testing. + + + + diff --git a/guides/settlements/index.mdx b/guides/settlements/index.mdx new file mode 100644 index 00000000..ec1ad39e --- /dev/null +++ b/guides/settlements/index.mdx @@ -0,0 +1,44 @@ +--- +title: 'Overview' +description: Propose, approve and manage two-way atomic transfers. +--- + + +![Settlements Profiles](/images/settlement-profiles.png) + +Use the Settlements API to facilitate simultaneous exchange of pre-funded assets. +Automate a variety of use cases that require two-party approval, including +net settlement of over-the-counter trades, withdrawal requests for tri-party collateral, payment requests, and bilateral settlement for marketplace end users. + +The simple request-and-approval workflow supports both one-directional and bidirectional transactions to allow a user to receive an asset (for example, send USDP) or simultaneously send and receive assets (for example, send USD and receive BTC and ETH). +Only when all parties are in agreement and assets are fully funded does the Settlements API allow for change of custody. +Upon completion, all settled assets are immediately available for trading, transferring, withdrawal or other supported activities. + +## Settlement Workflow + +The settlement workflow requires two parties to complete: The Source Profile owner who [initiates](/api-reference/endpoints/settlement/create-transaction) the transaction and the Target Profile owner who [approves](/api-reference/endpoints/settlement/affirm-transaction) the transaction. +Most integrations follow a similar workflow: + +1. Both parties agree on the transaction details and share counterparty Profile IDs outside of the Paxos Platform (for example, via email, Telegram, or other application). +1. The Source Profile owner [submits the transaction](/api-reference/endpoints/settlement/create-transaction) to the settlement platform. +1. The Target Profile owner receives a [notification](/guides/settlements/notification), reviews the transaction details and [approves the transaction](/api-reference/endpoints/settlement/affirm-transaction). +1. Both parties fund the associated Profiles via deposits if the requisite balances are not already present. +1. Settlement (movement of assets between Profiles) occurs soon after both parties have sufficient assets on the platform. +1. Once the transaction [settles](/guides/settlements/status), both parties can immediately utilize the new balance. + +## Get Started + + + + Set up and complete the settlement workflow in the Sandbox environment. + + + Learn more about settlement statuses. + + + Understand how settlement notifications work. + + + Get answers to common questions about the Settlements API. + + diff --git a/guides/settlements/notification.mdx b/guides/settlements/notification.mdx new file mode 100644 index 00000000..831416a1 --- /dev/null +++ b/guides/settlements/notification.mdx @@ -0,0 +1,15 @@ +--- +title: 'Notifications' +description: Understand how settlement notifications work. +--- + + +By default, each Profile owner receives an email notification when a settlement transaction is [created](/api-reference/endpoints/settlement/create-transaction) and upon each [status](/guides/settlements/status) change. +Currently, only email notifications are supported. +Websocket and desktop notifications are being considered for future releases. + +> To test email notifications in Sandbox, contact [Support](https://support.paxos.com) to enable notifications. + +All settlement email notifications use the same template: + +![Settlements Email Notification](/images/settlement-notification.png) diff --git a/guides/settlements/quickstart.mdx b/guides/settlements/quickstart.mdx new file mode 100644 index 00000000..1da57935 --- /dev/null +++ b/guides/settlements/quickstart.mdx @@ -0,0 +1,333 @@ +--- +title: 'Quickstart' +description: Set up and complete the settlement workflow in the Sandbox environment. +--- + + +The [settlement workflow](/guides/settlements#workflow) requires [two Profiles](#set-up-profiles), referred to in this guide as Source Profile (`source_profile_id`) and Target Profile (`target_profile_id`). +The Profiles are under the same Sandbox Account for simplicity and to allow completion of the steps with a single [authentication](#authenticate). +This guild also [funds](#fund) the Source Profile with BTC and ETH for the `DELIVER` leg and USD in the Target Profile for the `RECEIVE` leg before [creating the transaction request](#propose). + +> Contact your [Entity Manager](/guides/dashboard/roles#entity-manager) or [Support](https://support.paxos.com) if you run into any issues or don't have access to a Sandbox Account. + +## 1. Authenticate + +Add the `settlement:read_transaction` and `settlement:write_transaction` scopes to your [Sandbox Account](https://dashboard.sandbox.paxos.com) under the [API Management](https://dashboard.sandbox.paxos.com/admin/api) setting and then authenticate in Sandbox using the scopes. +Also include `funding:read_profile` and `funding:write_profile` for creating and funding [Profiles](/api-reference/endpoints/profiles). + +```shell highlight={5} +curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \ +--form grant_type=client_credentials \ +--form client_id={paxos_client_id} \ +--form client_secret={paxos_secret} \ +--form scope='settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile' +``` + +Confirm the response includes requisite scopes and save the `access_token` to use in the request authorization header throughout this guide. + +```json highlight={3,4} +{ + "access_token": "{access_token}", + "expires_in": 3599, // Seconds (59 Minutes and 59 Seconds) + "scope": "settlement:read_transaction settlement:write_transaction funding:read_profile funding:write_profile", + "token_type": "bearer" +} +``` + +## 2. Set Up Profiles + +[Create](/api-reference/endpoints/profiles/create-profile) two new Profiles in the Sandbox Account, one with `Source Profile` and the second with `Target Profile` as the `nickname`. + +### Create Source Profile + +```shell highlight={4} +curl --location 'https://api.sandbox.paxos.com/v2/profiles' \ +--header 'Authorization: Bearer {access_token}' \ +--data '{ + "nickname": "Source Profile" +}' +``` + +You will need the `id` from the response to [fund the Profile](#fund) and [propose a transaction](#propose). + +```json highlight={2} +{ + "id": "{profile_id}", // The source_profile_id in the Transaction object + "nickname": "Source Profile", + "type": "NORMAL" +} +``` +### Create Target Profile + +```shell highlight={4} +curl --location 'https://api.sandbox.paxos.com/v2/profiles' \ +--header 'Authorization: Bearer {access_token}' \ +--data '{ + "nickname": "Target Profile" +}' +``` + +You will need the `id` from the response to [fund the Profile](#fund) and [propose a transaction](#propose). + +```json highlight={2} +{ + "id": "{profile_id}", // The target_profile_id in the Transaction object + "nickname": "Target Profile", + "type": "NORMAL" +} +``` +## 3. Fund Profiles + +Next, use [Create Sandbox Deposit](/api-reference/endpoints/sandbox-deposits/create-sandbox-deposit) to fund the Profiles. + + + +This guide pre-funds all accounts prior to [creating a settlement request](#propose) for simplicity. +However, it is possible to create and approve a settlement request [before the funds are available](/guides/settlements/faq#assets). + + +### Fund Source Profile + +Deposit crypto into the Source Profile. +First, Bitcoin: + +```shell +curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ +--header 'Authorization: Bearer {access_token}' \ +--data ' + { + "asset": "BTC", + "amount": "2", + "crypto_network": "BITCOIN" + }' + ``` + Then add some Ethereum: + + ```shell +curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ +--header 'Authorization: Bearer {access_token}' \ +--data ' + { + "asset": "ETH", + "amount": "10", + "crypto_network": "ETHEREUM" + }' + ``` +Use [List Profile Balances](/api-reference/endpoints/profiles/list-profile-balances) to retrieve the Source Profile balance. +Include the `assets` query parameter to filter out all other assets. + +```shell +curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances?assets=BTC&assets=ETH' \ +--header 'Authorization: Bearer {access_token}' +``` +Confirm the Source Profile has at least 1 BTC and 5 ETH available for trading. + +```json highlight={5,10} +{ + "items": [ + { + "asset": "BTC", + "available": "2", + "trading": "0" + }, + { + "asset": "ETH", + "available": "10", + "trading": "0" + } + ] +} +``` +### Fund Target Profile + +Deposit USD into the Target Profile. +```shell +curl --location 'https://api.sandbox.paxos.com/v2/sandbox/profiles/{profile_id}' \ +--header 'Authorization: Bearer {access_token}' \ +--data ' + { + "asset": "USD", + "amount": "100000" + }' +``` + +Use [Get Profile Balance](/api-reference/endpoints/profiles/get-profile-balance) to retrieve the Target Profile USD balance. + +```shell +curl --location 'https://api.sandbox.paxos.com/v2/profiles/{profile_id}/balances/USD' \ +--header 'Authorization: Bearer {access_token}' +``` + +Confirm the Target Profile has at least $50,000 USD available for trading. + +```json highlight={3} +{ + "asset": "USD", + "available": "100000", + "trading": "0" +} +``` +## 4. Propose Transaction + +Using the Source Profile and Target Profile `profile_id` [created earlier](#set-up-profiles), use [Create Transaction](/api-reference/endpoints/settlement/create-transaction) to propose exchanging 1 BTC and 5 ETH (in the Source Profile balance) for $50,000 USD (in the Target Profile balance). The `ref_id` must be unique. The settlement window defaults apply if `settlement_window_start` and/or `settlement_window_end` are not specified. + +```shell highlight={4,5,6} +curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions' \ +--header 'Authorization: Bearer {access_token}' \ +--data '{ + "ref_id": "required_idempotence_id", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "legs": [ + { + "direction": "DELIVER", + "asset": "BTC", + "amount": "1.00" + }, + { + "direction": "DELIVER", + "asset": "ETH", + "amount": "5" + }, + { + "direction": "RECEIVE", + "asset": "USD", + "amount": "50000.00" + } + ] +}' +``` + +The acknowledgement response confirms the request has been received and provides the `Transaction` object. +The unique transaction `id` is used to [approve](#approve) and [retrieve](#check-status) the transaction, and the Source Profile owner can use the `id` to [cancel](/api-reference/endpoints/settlement/cancel-transaction) the `PENDING` transaction. +The transaction [status](/guides/settlements/status) can be used by either party to [retrieve a list of filtered transactions](/guides/settlements/status#list-transactions). + +```json highlight={2,28} +{ + "id": "{unique_transaction_id}", + "ref_id": "required_idempotence_id", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", // Defaults to current time + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", // Defaults to settlement_window_start plus 24 hours + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "legs": [ + { + "id": "{unique_leg_1_id}", + "direction": "DELIVER", // From Source Profile + "asset": "BTC", + "amount": "1" + }, + { + "id": "{unique_leg_2_id}", + "direction": "DELIVER", // From Source Profile + "asset": "ETH", + "amount": "5" + }, + { + "id": "{unique_leg_3_id}", + "direction": "RECEIVE", // From Target Profile + "asset": "USD", + "amount": "50000" + } + ], + "status": "PENDING", + "created_at": "YYYY-MM-DDT00:00:00Z", + "updated_at": "YYYY-MM-DDT00:00:00Z" +} +``` + +## 5. Approve Transaction + +The Target Profile owner [approves (affirms)](/api-reference/endpoints/settlement/affirm-transaction) the transaction. + + + +Since the same Paxos Account is used for both counterparty Profiles in this guide, you can use the same [authentication](#authenticate). + + + +Use the `Transaction.id` from the [propose step](#propose) as the `transaction_id`. +You can also [look up a transaction by status](/guides/settlements/status#list-transactions) to find the `id`. + +```shell +curl --location --request PUT 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}/affirm' \ +--header 'Authorization: Bearer {access_token}' +``` + +The acknowledgement response includes transaction information and the `AFFIRMED` [status](/guides/settlements/status) and `updated_at` timestamp. + +```json highlight={8,10} +{ + "id": "{unique_transaction_id}", + "ref_id": "required_idempotence_id", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "status": "AFFIRMED", + "created_at": "YYYY-MM-DDT00:00:00Z", + "updated_at": "YYYY-MM-DDT00:00:00Z" +} +``` + +## 6. Check Transaction Status + +Settlement of the `AFFIRMED` transaction occurs only when both counterparties fully fund their Profiles. + + + +Since both Profiles in this guide are [pre-funded](#set-up-profiles), the transaction settled within a few seconds. + + + +Either party can use [Get Transaction](/api-reference/endpoints/settlement/get-transaction) to check the [status](/guides/settlements/status). + +```shell +curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions/{transaction_id}' \ +--header 'Authorization: Bearer {access_token}' +``` + +The response includes the complete `Transaction` object. +When the transaction completes, the [status](/guides/settlements/status) and `updated_at` timestamp reflect the most recent activity. + +```json highlight={28,30} +{ + "id": "{unique_transaction_id}", + "ref_id": "required_idempotence_id", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "legs": [ + { + "id": "{unique_leg_1_id}", + "direction": "DELIVER", + "asset": "BTC", + "amount": "1" + }, + { + "id": "{unique_leg_2_id}", + "direction": "DELIVER", + "asset": "ETH", + "amount": "5" + }, + { + "id": "{unique_leg_3_id}", + "direction": "RECEIVE", + "asset": "USD", + "amount": "50000" + } + ], + "status": "SETTLED", + "created_at": "YYYY-MM-DDT00:00:00Z", + "updated_at": "YYYY-MM-DDT00:00:00Z" +} +``` + +## Next Steps + +- Create a settlement transaction before funding the Profiles. +- Learn more in the Settlements [FAQ](/guides/settlements/faq). +- Explore settlement methods and objects in the [Settlements API](/api-reference/endpoints/settlement). diff --git a/guides/settlements/status.mdx b/guides/settlements/status.mdx new file mode 100644 index 00000000..6229d89a --- /dev/null +++ b/guides/settlements/status.mdx @@ -0,0 +1,126 @@ +--- +title: 'Statuses' +description: Learn more about settlement statuses. +--- + + +The [settlement workflow](/guides/settlements/index#workflow) includes five statuses: + +- `PENDING`: Initial state of a settlement transaction upon creation by the Source Profile owner (`source_profile_id`). +- `AFFIRMED`: The settlement transaction has been approved by the Target Profile owner (`target_profile_id`) and will be eligible for settlement once within the transaction window (`settlement_window_start` → `settlement_window_end`). +- `SETTLED`: The assets in the transaction have successfully been transferred. +- `EXPIRED`: The settlement transaction is no longer eligible for settlement. +- `CANCELED`: The settlement transaction was canceled by the Source Profile owner. + +When a settlement transactions is [created](/api-reference/endpoints/settlement/create-transaction), it starts in `PENDING` status. +The assets do not need to be available in the Profiles at this stage. +In the `PENDING` state, two actions can be taken: +- The Source Profile owner [cancels](/api-reference/endpoints/settlement/cancel-transaction) the transaction. Status transitions to `CANCELLED`. +- The Target Profile owner [approves](/api-reference/endpoints/settlement/affirm-transaction) the transaction. Status transitions to `AFFIRMED`. + +Once the required asset balances are in the respective Profiles, settlement occurs. Status transactions to `SETTLED` when complete. + +```mermaid +flowchart LR + A[PENDING] ==> | Target Profile owner approves | B[AFFIRMED] ==>C[SETTLED] + A --> | Settlement window expires | D[EXPIRED] + A --> | Source Profile owner cancels | E[CANCELLED] + B --> D +``` + +Transactions in the `PENDING` or `AFFIRMED` state at the end of the settlement window (`settlement_window_end`) automatically transition to `EXPIRED`. + +## Find Transactions by Status + +Either involved party can use [List Transactions](/api-reference/endpoints/settlement/list-transactions) to retrieve all the transactions they are counterparty to. +Use the `statuses` query parameter to filter based on status. + + + +You must specify the `limit` of items per page or an error returns. + + + +```shell +curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?statuses=PENDING&statuses=AFFIRMED&limit=2' \ +--header 'Authorization: Bearer {access_token}' +``` + +Based on the request parameters, the response contains the two most recent open transactions. + +```json highlight={30,61,66} +{ + "items": [ + { + "id": "{unique_transaction_id}", + "ref_id": "required_idempotence_id_1", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "legs": [ + { + "id": "{unique_leg_1_id}", + "direction": "DELIVER", + "asset": "BTC", + "amount": "1" + }, + { + "id": "{unique_leg_2_id}", + "direction": "DELIVER", + "asset": "ETH", + "amount": "5" + }, + { + "id": "{unique_leg_3_id}", + "direction": "RECEIVE", + "asset": "USD", + "amount": "40000" + } + ], + "status": "PENDING", + "created_at": "YYYY-MM-DDT00:00:00Z", + "updated_at": "YYYY-MM-DDT00:00:00Z" + }, + { + "id": "{unique_transaction_id}", + "ref_id": "required_idempotence_id", + "settlement_window_start": "YYYY-MM-DDT00:00:00Z", + "settlement_window_end": "YYYY-MM-DDT00:00:00Z", + "source_profile_id": "{profile_id}", + "target_profile_id": "{profile_id}", + "legs": [ + { + "id": "{unique_leg_1_id}", + "direction": "DELIVER", + "asset": "BTC", + "amount": "1" + }, + { + "id": "{unique_leg_2_id}", + "direction": "DELIVER", + "asset": "ETH", + "amount": "5" + }, + { + "id": "{unique_leg_3_id}", + "direction": "RECEIVE", + "asset": "USD", + "amount": "40000" + } + ], + "status": "AFFIRMED", + "created_at": "YYYY-MM-DDT00:00:00Z", + "updated_at": "YYYY-MM-DDT00:00:00Z" + } + ], + "next_page_cursor": "{page_cursor_value}" +} +``` + +To view more items, add the `page_cursor` query parameter to the request. + +```shell highlight={1} +curl --location 'https://api.sandbox.paxos.com/v2/settlement/transactions?limit=2&page_cursor={page_cursor_value}' \ +--header 'Authorization: Bearer {access_token}' +``` diff --git a/guides/settlements/triparty.mdx b/guides/settlements/triparty.mdx new file mode 100644 index 00000000..77a3b599 --- /dev/null +++ b/guides/settlements/triparty.mdx @@ -0,0 +1,4 @@ +--- +title: 'Triparty Collateral Management' +description: Using the Settlements API for triparty collateral management. +---