Skip to main content

​
Understanding Orchestrations

Orchestrations allow customers to perform complex actions by executing multi-step workflows to move between assets, networks, and rails. There are two types of Orchestrations: ad-hoc, and rule-based. Ad-hoc orchestrations are one-off orchestrations that can be triggered to move funds from a profile to a number of destinations. Rule-based orchestrations are based off a rule which is triggered upon deposit to a crypto address or a bank account. As we’ll show in the mint, convert, and redeem pages these orchestrations can be harnessed to perform a number of operations.

​
Orchestration Flow Diagram

The following diagram illustrates the possible orchestration routes within the Paxos platform:
  • Rule-based Orchestrations: Originate from external fiat deposits (bank accounts) or external crypto deposits (blockchain). These trigger automatically when a matching rule exists.
  • Ad-hoc Orchestrations: Must originate from internal profiles but can route to profiles, external fiat accounts, or external crypto addresses.
  • Profile-to-Profile Transfers: Customers with multiple internal profiles can execute ad-hoc transfers between them.
  • Asset Conversion: Any transfer can involve different source and destination assets (not shown for clarity but applies to all routes).

​
Required Authentication Scopes

To use orchestrations, you’ll need the following OAuth scopes when authenticating:

​
Core Orchestration Operations

  • Ad-hoc Orchestrations:
    • orchestration:read_orchestration - View orchestration status
    • orchestration:write_orchestration - Create orchestrations
  • Rule-based Orchestrations:
    • orchestration:read_orchestration_rule - View orchestration rules
    • orchestration:write_orchestration_rule - Create and manage rules

​
Supporting Operations

  • Webhook Monitoring:
    • events:read_event - Read the object payloads for webhook events
  • Fiat Operations (for bank withdrawals):
    • transfer:read_fiat_account - View fiat account details
    • transfer:write_fiat_account - Create fiat accounts
    • transfer:read_fiat_deposit_instructions - View deposit instructions
    • transfer:write_fiat_deposit_instructions - Create deposit instructions
  • Crypto Address Registration (optional):
    • transfer:read_crypto_destination_address - View registered addresses
    • transfer:write_crypto_destination_address - Register new addresses

​
Monitoring Orchestration Status

Orchestrations can exist in three states. To monitor them there’s a few options.

​
Recommended: Using Webhooks

Subscribe to orchestration webhooks for real-time status monitoring. This is the recommended approach as it provides immediate notifications without polling.
Webhooks are triggered upon each status change in the orchestration lifecycle. The webhook payload contains an event ID that you use to fetch the full orchestration_status_change event details: Fetch the event details to get the orchestration information:
When orchestrations are triggered by a rule, the event object will include an orchestration_rule_id field linking back to the originating rule.

​
Alternative: Polling with API

Use List Orchestrations to check orchestration status: The response includes all orchestrations for the profile with their current status:

​
Required Setup for External Crypto Destinations

When sending funds to external crypto addresses in orchestrations, you must first register the destination address using Put Crypto Destination Address. This is required to:
  • Store travel rule metadata for compliance
  • Obtain a crypto_address_id for use in orchestrations
  • Manage approved destination addresses

​
Adding a Crypto Destination Address

​
Using Registered Addresses in Orchestrations

Once registered, reference the address by its ID in orchestration destinations: 
"destination": {
  "crypto": {
    "crypto_address_id": "crypto_addr_123abc"
  }
}
⌘I