Create Orchestration

curl --request POST \
  --url https://api.paxos.com/v2/orchestration/orchestrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ref_id": "orch-usdc-usdg-a3b1c2d4",
  "identity_id": "b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
  "account_id": "c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8",
  "source_asset": "USDC",
  "source_amount": "100",
  "destination_asset": "USDG",
  "source": {
    "profile": {
      "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c"
    }
  },
  "destination": {
    "crypto": {
      "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9"
    }
  },
  "metadata": {
    "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f"
  }
}
'

import requests

url = "https://api.paxos.com/v2/orchestration/orchestrations"

payload = {
    "ref_id": "orch-usdc-usdg-a3b1c2d4",
    "identity_id": "b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
    "account_id": "c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8",
    "source_asset": "USDC",
    "source_amount": "100",
    "destination_asset": "USDG",
    "source": { "profile": { "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c" } },
    "destination": { "crypto": { "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9" } },
    "metadata": { "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ref_id: 'orch-usdc-usdg-a3b1c2d4',
    identity_id: 'b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7',
    account_id: 'c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8',
    source_asset: 'USDC',
    source_amount: '100',
    destination_asset: 'USDG',
    source: {profile: {profile_id: '7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c'}},
    destination: {crypto: {address_id: 'd4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9'}},
    metadata: {my_id: '4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f'}
  })
};

fetch('https://api.paxos.com/v2/orchestration/orchestrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paxos.com/v2/orchestration/orchestrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ref_id' => 'orch-usdc-usdg-a3b1c2d4',
    'identity_id' => 'b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7',
    'account_id' => 'c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8',
    'source_asset' => 'USDC',
    'source_amount' => '100',
    'destination_asset' => 'USDG',
    'source' => [
        'profile' => [
                'profile_id' => '7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c'
        ]
    ],
    'destination' => [
        'crypto' => [
                'address_id' => 'd4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9'
        ]
    ],
    'metadata' => [
        'my_id' => '4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paxos.com/v2/orchestration/orchestrations"

	payload := strings.NewReader("{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paxos.com/v2/orchestration/orchestrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paxos.com/v2/orchestration/orchestrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "e5f6a7b8-9c0d-1e2f-3a4b-c5d6e7f8a9b0",
  "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c",
  "customer_id": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "ref_id": "orch-usdc-usdg-a3b1c2d4",
  "source_asset": "USDC",
  "destination_asset": "USDG",
  "source_amount": "100",
  "status": "PROCESSING",
  "source": {
    "profile": {
      "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c"
    }
  },
  "destination": {
    "crypto": {
      "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9"
    }
  },
  "created_at": "2026-04-20T12:30:01.397730Z",
  "updated_at": "2026-04-20T12:30:01.397730Z",
  "metadata": {
    "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f"
  }
}

Orchestration

Create Orchestration

Creates a one-time orchestration that moves assets from a source profile to a destination. Use this endpoint when funds already reside on the Paxos platform and need to be transferred or converted as part of a single workflow.

A request to create an orchestration can fail with one of the following types of errors:

Insufficient Funds if the Profile (profile_id) has insufficient available balance to fund the execution.
Already Exists if an orchestration with the same external ID (ref_id) has already been created.

POST

orchestration

orchestrations

Create Orchestration

curl --request POST \
  --url https://api.paxos.com/v2/orchestration/orchestrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ref_id": "orch-usdc-usdg-a3b1c2d4",
  "identity_id": "b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
  "account_id": "c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8",
  "source_asset": "USDC",
  "source_amount": "100",
  "destination_asset": "USDG",
  "source": {
    "profile": {
      "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c"
    }
  },
  "destination": {
    "crypto": {
      "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9"
    }
  },
  "metadata": {
    "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f"
  }
}
'

import requests

url = "https://api.paxos.com/v2/orchestration/orchestrations"

payload = {
    "ref_id": "orch-usdc-usdg-a3b1c2d4",
    "identity_id": "b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
    "account_id": "c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8",
    "source_asset": "USDC",
    "source_amount": "100",
    "destination_asset": "USDG",
    "source": { "profile": { "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c" } },
    "destination": { "crypto": { "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9" } },
    "metadata": { "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ref_id: 'orch-usdc-usdg-a3b1c2d4',
    identity_id: 'b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7',
    account_id: 'c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8',
    source_asset: 'USDC',
    source_amount: '100',
    destination_asset: 'USDG',
    source: {profile: {profile_id: '7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c'}},
    destination: {crypto: {address_id: 'd4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9'}},
    metadata: {my_id: '4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f'}
  })
};

fetch('https://api.paxos.com/v2/orchestration/orchestrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paxos.com/v2/orchestration/orchestrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ref_id' => 'orch-usdc-usdg-a3b1c2d4',
    'identity_id' => 'b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7',
    'account_id' => 'c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8',
    'source_asset' => 'USDC',
    'source_amount' => '100',
    'destination_asset' => 'USDG',
    'source' => [
        'profile' => [
                'profile_id' => '7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c'
        ]
    ],
    'destination' => [
        'crypto' => [
                'address_id' => 'd4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9'
        ]
    ],
    'metadata' => [
        'my_id' => '4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paxos.com/v2/orchestration/orchestrations"

	payload := strings.NewReader("{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paxos.com/v2/orchestration/orchestrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paxos.com/v2/orchestration/orchestrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ref_id\": \"orch-usdc-usdg-a3b1c2d4\",\n  \"identity_id\": \"b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7\",\n  \"account_id\": \"c3d4e5f6-7a8b-9c0d-1e2f-a3b4c5d6e7f8\",\n  \"source_asset\": \"USDC\",\n  \"source_amount\": \"100\",\n  \"destination_asset\": \"USDG\",\n  \"source\": {\n    \"profile\": {\n      \"profile_id\": \"7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c\"\n    }\n  },\n  \"destination\": {\n    \"crypto\": {\n      \"address_id\": \"d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9\"\n    }\n  },\n  \"metadata\": {\n    \"my_id\": \"4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "e5f6a7b8-9c0d-1e2f-3a4b-c5d6e7f8a9b0",
  "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c",
  "customer_id": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "ref_id": "orch-usdc-usdg-a3b1c2d4",
  "source_asset": "USDC",
  "destination_asset": "USDG",
  "source_amount": "100",
  "status": "PROCESSING",
  "source": {
    "profile": {
      "profile_id": "7c4e8f2a-1d3b-4a5e-9f6c-8b2d7e0a4f1c"
    }
  },
  "destination": {
    "crypto": {
      "address_id": "d4e5f6a7-8b9c-0d1e-2f3a-b4c5d6e7f8a9"
    }
  },
  "created_at": "2026-04-20T12:30:01.397730Z",
  "updated_at": "2026-04-20T12:30:01.397730Z",
  "metadata": {
    "my_id": "4f8a2b6c-9d1e-4c3a-b5f7-0e2d8a7c1b9f"
  }
}

OAuth Scope

orchestration:write_orchestration

Authorizations

Authorization

string

header

required

Paxos APIs use OAuth 2 with the client credentials grant flow.

Token URLs:

Production: https://oauth.paxos.com/oauth2/token
Sandbox: https://oauth.sandbox.paxos.com/oauth2/token

Learn more in the API credentials guide →

Body

application/json

ref_id

string

required

A client or system-specified unique identifier for the orchestration - used for idempotency protection. Retries of a request should use the same ref_id to avoid duplicate transactions.

source_asset

string

required

destination_asset

string

required

source_amount

string<decimal>

required

identity_id

string

account_id

string

source

object

Show child attributes

destination

object

Show child attributes

metadata

Metadata associated with the orchestration · object

Show child attributes

Response

200 - application/json

A successful response.

Orchestrations can be created directly via the CreateOrchestration endpoint, or indirectly by an incoming deposit which matches an OrchestrationRule previously defined with the CreateOrchestrationRule endpoint.

string

profile_id

string

identity_id

string

account_id

string

customer_id

string

ref_id

string

A client or system-specified unique identifier for the orchestration - used for idempotency protection. Retries of a request should use the same ref_id to avoid duplicate transactions. For system-initiated orchestrations generated by invocation of an orchestration rule, the ref_id is generated the system.

source_asset

string

destination_asset

string

source_amount

string<decimal>

source_transfer

object

TransferDetails refers to a specific Transfer and encodes its current status.

Show child attributes

destination_transfer

object

TransferDetails refers to a specific Transfer and encodes its current status.

Show child attributes

status

enum<string>

Status represents the current state of an orchestration.

PROCESSING: The orchestration is actively being processed.
COMPLETED: The orchestration completed successfully.
FAILED: The orchestration failed during processing.
PENDING: The orchestration is awaiting approval before processing begins. Once approved, it transitions to PROCESSING. If rejected, it transitions to REJECTED.
REJECTED: The orchestration was rejected during approval.

Available options:

PROCESSING,

COMPLETED,

FAILED,

PENDING,

REJECTED

fail_reason

object

Show child attributes

source

object

Show child attributes

destination

object

Show child attributes

orchestration_rule_id

string

The ID of the orchestration rule which triggered this orchestration. Can be empty for ad-hoc orchestrations.

created_at

string<date-time>

updated_at

string<date-time>

metadata

Metadata associated with the orchestration · object

Show child attributes

List Orchestrations Get Orchestration

⌘I