Execute a transaction (send)

curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "quoteId": "qt_0gq9aesz4wb5etdv88z1j61qcm",
  "metadata": {
    "orderId": "order_12345"
  }
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/transactions"

payload = {
    "quoteId": "qt_0gq9aesz4wb5etdv88z1j61qcm",
    "metadata": { "orderId": "order_12345" }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({quoteId: 'qt_0gq9aesz4wb5etdv88z1j61qcm', metadata: {orderId: 'order_12345'}})
};

fetch('https://sandbox-api.polygon.technology/v0.13/transactions', 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://sandbox-api.polygon.technology/v0.13/transactions",
  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([
    'quoteId' => 'qt_0gq9aesz4wb5etdv88z1j61qcm',
    'metadata' => [
        'orderId' => 'order_12345'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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://sandbox-api.polygon.technology/v0.13/transactions"

	payload := strings.NewReader("{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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://sandbox-api.polygon.technology/v0.13/transactions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/transactions")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}"

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

{
  "id": "txn_hdgebv2mns4af7pgs5r6kkacxh",
  "object": "transaction",
  "sourceToDestination": "cryptoToFiatAccount",
  "status": "processing",
  "subStatus": "processing.fundsPulled",
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "precursor": {
    "type": "quote",
    "id": "qt_0gq9aesz4wb5etdv88z1j61qcm"
  },
  "source": {
    "party": {
      "relationship": "customer",
      "id": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
      "name": "Jane Smith"
    },
    "type": "walletCrypto",
    "category": "crypto",
    "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn",
    "asset": "usdc",
    "network": "polygon",
    "displayName": "0x7B3A9F2C4D1eA8bf6390cE5D2b7fA104c8e3D9B1"
  },
  "destination": {
    "party": {
      "relationship": "externalRegistered",
      "id": "ctp_yp5z8m7n22svc0vh6edqgcfdat",
      "name": "Alice Smith"
    },
    "type": "bankUs",
    "category": "fiatAccount",
    "id": "ext_fky491gakzj0dd46qb6whsr2vq",
    "asset": "usd",
    "network": "ach",
    "secCode": "web",
    "displayName": "••••1234",
    "payoutOrigin": {
      "type": "bank",
      "id": "va_e6nfr4q5jj9bwgb1pyx70wzxta",
      "accountHolder": "customer",
      "accountHolderName": "Jane Smith"
    }
  },
  "pricing": {
    "source": {
      "asset": "usdc",
      "amountGross": "100.00",
      "amountNet": "100.00"
    },
    "destination": {
      "asset": "usd",
      "amountGross": "100.00",
      "amountNet": "100.00"
    },
    "fees": [],
    "exchangeRate": "1.0000",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "0.00"
  },
  "tracking": [],
  "estimatedArrival": "2026-03-14T19:30:00Z",
  "metadata": {
    "orderId": "order_12345"
  },
  "createdAt": "2026-03-14T19:00:00Z",
  "updatedAt": "2026-03-14T19:00:20Z"
}

{
  "error": "CounterpartyUnresolved",
  "code": 10271,
  "msg": "destination external account is required",
  "cause": "<string>"
}

{
  "error": "EreborConfigMissing",
  "code": 10025,
  "msg": "the provider integration is not configured for this partner",
  "cause": "<string>"
}

{
  "error": "QuoteNotFound",
  "code": 10260,
  "msg": "quote not found",
  "cause": "<string>"
}

{
  "error": "ConcurrentModification",
  "code": 10232,
  "msg": "pair changed since it was inspected; re-read its status and retry with the current version",
  "cause": "<string>"
}

{
  "error": "BankBeneficiaryNotVerified",
  "code": 10293,
  "msg": "bank beneficiary is not verified",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "AwaitingDepositUnsupported",
  "code": 10300,
  "msg": "awaiting-deposit funding is not supported",
  "cause": "<string>"
}

{
  "id": "<string>",
  "object": "transaction",
  "status": "processing",
  "subStatus": "processing.fundsPulled",
  "customerId": "<string>",
  "precursor": {
    "type": "quote",
    "id": "<string>"
  },
  "source": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>"
  },
  "destination": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>",
    "payoutOrigin": {
      "type": "bank",
      "id": "<string>",
      "accountHolder": "customer",
      "accountHolderName": "<string>"
    },
    "companyDiscretionaryData": "<string>"
  },
  "pricing": {
    "fees": [
      {
        "type": "<string>",
        "side": "source",
        "asset": "<string>",
        "amount": "<string>"
      }
    ],
    "source": {
      "asset": "<string>",
      "amountGross": "<string>",
      "amountNet": "<string>"
    },
    "destination": {
      "asset": "<string>",
      "amountGross": "<string>",
      "amountNet": "<string>"
    },
    "exchangeRate": "<string>",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "<string>"
  },
  "tracking": [
    {
      "scheme": "<string>",
      "value": "<string>",
      "leg": "source",
      "network": "<string>",
      "assignedBy": "<string>",
      "url": "<string>"
    }
  ],
  "sourceToDestination": "cryptoToCrypto",
  "customer": {
    "id": "<string>",
    "name": "<string>"
  },
  "estimatedArrival": "2023-11-07T05:31:56Z",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "occurredAt": "2023-11-07T05:31:56Z",
    "recoverable": true,
    "manualRecovery": {
      "type": "manualRecovery",
      "custodian": "ANCHORAGE_SG",
      "instructions": "<string>",
      "referenceFields": {
        "transactionId": "<string>",
        "sourceTxHash": "<string>"
      }
    }
  },
  "hold": {
    "required": true,
    "type": "informationRequested",
    "instructions": "<string>",
    "requestedFrom": "<string>",
    "since": "2023-11-07T05:31:56Z",
    "deadline": "2023-11-07T05:31:56Z",
    "resolvedAt": "2023-11-07T05:31:56Z",
    "customerId": "<string>"
  },
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "projectId": "<string>"
}

POST

transactions

Execute a transaction (send)

curl --request POST \
  --url https://sandbox-api.polygon.technology/v0.13/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "quoteId": "qt_0gq9aesz4wb5etdv88z1j61qcm",
  "metadata": {
    "orderId": "order_12345"
  }
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/transactions"

payload = {
    "quoteId": "qt_0gq9aesz4wb5etdv88z1j61qcm",
    "metadata": { "orderId": "order_12345" }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({quoteId: 'qt_0gq9aesz4wb5etdv88z1j61qcm', metadata: {orderId: 'order_12345'}})
};

fetch('https://sandbox-api.polygon.technology/v0.13/transactions', 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://sandbox-api.polygon.technology/v0.13/transactions",
  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([
    'quoteId' => 'qt_0gq9aesz4wb5etdv88z1j61qcm',
    'metadata' => [
        'orderId' => 'order_12345'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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://sandbox-api.polygon.technology/v0.13/transactions"

	payload := strings.NewReader("{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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://sandbox-api.polygon.technology/v0.13/transactions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/transactions")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quoteId\": \"qt_0gq9aesz4wb5etdv88z1j61qcm\",\n  \"metadata\": {\n    \"orderId\": \"order_12345\"\n  }\n}"

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

{
  "id": "txn_hdgebv2mns4af7pgs5r6kkacxh",
  "object": "transaction",
  "sourceToDestination": "cryptoToFiatAccount",
  "status": "processing",
  "subStatus": "processing.fundsPulled",
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "precursor": {
    "type": "quote",
    "id": "qt_0gq9aesz4wb5etdv88z1j61qcm"
  },
  "source": {
    "party": {
      "relationship": "customer",
      "id": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
      "name": "Jane Smith"
    },
    "type": "walletCrypto",
    "category": "crypto",
    "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn",
    "asset": "usdc",
    "network": "polygon",
    "displayName": "0x7B3A9F2C4D1eA8bf6390cE5D2b7fA104c8e3D9B1"
  },
  "destination": {
    "party": {
      "relationship": "externalRegistered",
      "id": "ctp_yp5z8m7n22svc0vh6edqgcfdat",
      "name": "Alice Smith"
    },
    "type": "bankUs",
    "category": "fiatAccount",
    "id": "ext_fky491gakzj0dd46qb6whsr2vq",
    "asset": "usd",
    "network": "ach",
    "secCode": "web",
    "displayName": "••••1234",
    "payoutOrigin": {
      "type": "bank",
      "id": "va_e6nfr4q5jj9bwgb1pyx70wzxta",
      "accountHolder": "customer",
      "accountHolderName": "Jane Smith"
    }
  },
  "pricing": {
    "source": {
      "asset": "usdc",
      "amountGross": "100.00",
      "amountNet": "100.00"
    },
    "destination": {
      "asset": "usd",
      "amountGross": "100.00",
      "amountNet": "100.00"
    },
    "fees": [],
    "exchangeRate": "1.0000",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "0.00"
  },
  "tracking": [],
  "estimatedArrival": "2026-03-14T19:30:00Z",
  "metadata": {
    "orderId": "order_12345"
  },
  "createdAt": "2026-03-14T19:00:00Z",
  "updatedAt": "2026-03-14T19:00:20Z"
}

{
  "error": "CounterpartyUnresolved",
  "code": 10271,
  "msg": "destination external account is required",
  "cause": "<string>"
}

{
  "error": "EreborConfigMissing",
  "code": 10025,
  "msg": "the provider integration is not configured for this partner",
  "cause": "<string>"
}

{
  "error": "QuoteNotFound",
  "code": 10260,
  "msg": "quote not found",
  "cause": "<string>"
}

{
  "error": "ConcurrentModification",
  "code": 10232,
  "msg": "pair changed since it was inspected; re-read its status and retry with the current version",
  "cause": "<string>"
}

{
  "error": "BankBeneficiaryNotVerified",
  "code": 10293,
  "msg": "bank beneficiary is not verified",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "AwaitingDepositUnsupported",
  "code": 10300,
  "msg": "awaiting-deposit funding is not supported",
  "cause": "<string>"
}

{
  "id": "<string>",
  "object": "transaction",
  "status": "processing",
  "subStatus": "processing.fundsPulled",
  "customerId": "<string>",
  "precursor": {
    "type": "quote",
    "id": "<string>"
  },
  "source": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>"
  },
  "destination": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>",
    "payoutOrigin": {
      "type": "bank",
      "id": "<string>",
      "accountHolder": "customer",
      "accountHolderName": "<string>"
    },
    "companyDiscretionaryData": "<string>"
  },
  "pricing": {
    "fees": [
      {
        "type": "<string>",
        "side": "source",
        "asset": "<string>",
        "amount": "<string>"
      }
    ],
    "source": {
      "asset": "<string>",
      "amountGross": "<string>",
      "amountNet": "<string>"
    },
    "destination": {
      "asset": "<string>",
      "amountGross": "<string>",
      "amountNet": "<string>"
    },
    "exchangeRate": "<string>",
    "fixedAmountSide": "source",
    "sponsorGas": true,
    "sponsorGasCost": "<string>"
  },
  "tracking": [
    {
      "scheme": "<string>",
      "value": "<string>",
      "leg": "source",
      "network": "<string>",
      "assignedBy": "<string>",
      "url": "<string>"
    }
  ],
  "sourceToDestination": "cryptoToCrypto",
  "customer": {
    "id": "<string>",
    "name": "<string>"
  },
  "estimatedArrival": "2023-11-07T05:31:56Z",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "occurredAt": "2023-11-07T05:31:56Z",
    "recoverable": true,
    "manualRecovery": {
      "type": "manualRecovery",
      "custodian": "ANCHORAGE_SG",
      "instructions": "<string>",
      "referenceFields": {
        "transactionId": "<string>",
        "sourceTxHash": "<string>"
      }
    }
  },
  "hold": {
    "required": true,
    "type": "informationRequested",
    "instructions": "<string>",
    "requestedFrom": "<string>",
    "since": "2023-11-07T05:31:56Z",
    "deadline": "2023-11-07T05:31:56Z",
    "resolvedAt": "2023-11-07T05:31:56Z",
    "customerId": "<string>"
  },
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "projectId": "<string>"
}

Authorizations

Authorization

string

header

required

Token from POST /auth/token

Headers

Idempotency-Key

string

required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Body

application/json

Request body for executing a transaction. References the quote to accept; the card and source wallet are taken from that quote. An external buy delivers to the quote's destination address when the destination is walletExternal, and otherwise to the customer's custody wallet on the destination chain; with no such address it is rejected with 422 ExternalDeliveryWalletRequired.

quoteId

string

required

The quote to accept (qt_ prefix). Must be open with non-expired pricing.

deviceFingerprint

string

Device fingerprint of the end user, used for risk screening.

webSessionId

string

Risk-session identifier generated client-side by the Sardine SDK (initialized with the customer's riskId). Required when the precursor quote's source or destination funding instrument is a card; ignored otherwise. Missing when required is rejected with 422 RiskSessionRequired.

metadata

object

Free-form key-value pairs stored on the resource and echoed back on reads.

Hide child attributes

metadata.{key}

string

Response

The request has succeeded and a new resource has been created as a result.

A single movement of money from a source to a destination. Created by accepting a quote, or generated automatically by a deposit address, virtual account, or cash-in. Track its progress with status.

string

required

Transaction ID (txn_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

object

enum<string>

required

Resource type discriminator. Always "transaction".

Available options:

transaction

status

enum<string>

required

Current lifecycle status. See subStatus for finer granularity.

Available options:

processing,

awaitingAction,

completed,

failed

subStatus

enum<string>

required

Status-scoped sub-state (e.g. processing.fundsPulled). Always present: each status carries a default member (e.g. processing.initiated) when no more specific value applies.

Available options:

processing.fundsPulled,

processing.cashPickupReady,

processing.underReview,

completed.cashPickupCollected,

completed.cashPickupExpired,

awaitingAction.informationRequested,

awaitingAction.awaitingSenderAttribution,

awaitingAction.depositAddressFrozen,

awaitingAction.depositAddressInactive,

failed.attributionTimeout,

failed.depositAddressFrozenTimeout,

failed.depositAddressInactiveTimeout,

failed.depositAddressClosed,

processing.awaitingCryptoOut,

processing.cryptoOut,

processing.awaitingFiatOut,

processing.fiatOut,

processing.inboundPending,

processing.inboundProcessing,

failed.inboundFailed,

failed.returnPending,

failed.returnStarted,

failed.returnComplete,

failed.returnFailed,

processing.initiated,

completed.settled,

failed.unspecified,

failed.expired,

failed.providerDeclined,

failed.outboundFailed

customerId

string

required

The OMS customer that owns this record — the sender on a transaction (cst_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

precursor

object | null

required

What created this transaction, as a uniform {type, id} reference — dereference the resource by id for its full record. A custodial-wallet deposit renders {type: walletDeposit, id: null}. null remains only for a genuine out-of-band arrival with no recognised origin at all; the manual arm (id: null) is reserved for a future operator-initiated transaction, distinct from either.

Hide child attributes

precursor.type

enum<string>

required

Available options:

quote,

depositAddress,

virtualAccount,

cashIn,

manual,

walletDeposit

precursor.id

string | null

required

qt_ / da_ / va_ / ci_. Null for manual and walletDeposit.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

source

OMS wallet · object

required

The funding side: a typed instrument carrying identity and detail.

Hide child attributes

source.type

enum<string>

required

Type discriminator.

Available options:

walletCrypto

source.category

enum<string>

required

High-level grouping: fiatAccount for bank or card accounts, crypto for wallets.

Available options:

crypto

source.id

string | null

required

OMS wallet ID (wlt_ prefix). Dereference via GET /wallets/{id}. Null while a deposit is still in flight and the wallet it lands in has not resolved yet.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

source.asset

string

required

Canonical asset identifier.

source.network

string

required

Network identifier.

source.displayName

string

required

Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN.

source.party

object

Structured identity of who is on this side.

Hide child attributes

source.party.relationship

enum<string>

required

Which kind of party this is.

Available options:

customer,

otherCustomer,

externalRegistered,

externalUnregistered

source.party.id

string | null

required

cst_ for customer/otherCustomer; ctp_ for externalRegistered; null for externalUnregistered.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

source.party.name

string | null

required

Display name. Null only when genuinely unknown (an unattributed external sender).

source.memo

string

Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (bankUs, bankIban, bankCanada).

destination

OMS wallet · object

required

The receiving side: a typed instrument plus payoutOrigin.

Hide child attributes

destination.type

enum<string>

required

Type discriminator.

Available options:

walletCrypto

destination.category

enum<string>

required

High-level grouping: fiatAccount for bank or card accounts, crypto for wallets.

Available options:

crypto

destination.id

string | null

required

OMS wallet ID (wlt_ prefix). Dereference via GET /wallets/{id}. Null while a deposit is still in flight and the wallet it lands in has not resolved yet.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

destination.asset

string

required

Canonical asset identifier.

destination.network

string

required

Network identifier.

destination.displayName

string

required

Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN.

destination.party

object

Structured identity of who is on this side.

Hide child attributes

destination.party.relationship

enum<string>

required

Which kind of party this is.

Available options:

customer,

otherCustomer,

externalRegistered,

externalUnregistered

destination.party.id

string | null

required

cst_ for customer/otherCustomer; ctp_ for externalRegistered; null for externalUnregistered.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

destination.party.name

string | null

required

Display name. Null only when genuinely unknown (an unattributed external sender).

destination.memo

string

destination.payoutOrigin

object

Where last-mile delivery is sent from, as a uniform {type, id} reference — response-only. id is the Virtual Account (va_) or OMS wallet (wlt_) funding the leg; null before execution (Quote / Deposit Address echo the choice only) or when the origin has no partner-visible resource. Rail identifiers for the last-mile transfer live in the top-level tracking array with leg: destination — not here.

Hide child attributes

destination.payoutOrigin.type

enum<string>

required

Available options:

bank,

blockchain

destination.payoutOrigin.id

string | null

required

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

destination.payoutOrigin.accountHolder

enum<string> | null

required

Whose legal identity the payment is sent under. Determined by OMS from the route's configuration — not a request field. Always present; null when OMS cannot determine it, and on destinations that have no sending legal identity (cash payouts, and crypto payouts outside a Deposit Address). A bank payout that goes out under the payment provider or the partner records that holder just before it is sent to the provider, and reports it only while a payout was or may have been created there; a send interrupted after the holder was recorded and before it went out has an unknown outcome and may report it. A failed send known to have created no payout at the provider, and a payout sent before holders were recorded (there is no backfill), report the fallback value instead, which may differ from the holder actually used. The fallback value, also reported before a holder is recorded and for payouts that always go out under the customer's own name, is the Deposit Address's value for the destination type the transaction pays (see DepositAddressPayoutOrigin) on a transaction created from a Deposit Address, and the value its route implies on any other.

Available options:

customer,

paymentProvider,

partner

destination.payoutOrigin.accountHolderName

string | null

required

The legal name the payment is sent under, resolved from accountHolder — the customer's own legal name for customer, the owning customer's legal name for partner (for now; a partner-level name may replace it later), or the payment provider's name for paymentProvider, which differs between a bank origin ("Coinme Inc FBO its Customers") and a blockchain origin. This is what the recipient sees as the sender. Like accountHolder and unlike id, it is populated as soon as it is determinable, so it appears on Quote and Deposit Address responses as well as Transactions. Null whenever accountHolder is null, and null on event payloads for customer and partner.

destination.companyDiscretionaryData

string

Echo of the ACH companyDiscretionaryData supplied on the originating request. Null/absent on non-ACH destinations or when not supplied.

pricing

object

required

Consolidated economics.

Hide child attributes

pricing.fees

object[]

required

Every fee deducted across both sides. [] when there are none — never omitted, never null.

Hide child attributes

pricing.fees.type

string

required

Fee kind. OPEN — clients must tolerate an unrecognised type. Known values today: "developer" (always 0 in alpha), "oms", "gas".

pricing.fees.side

enum<string>

required

Which side this fee was deducted from.

Available options:

source,

destination

pricing.fees.asset

string

required

Currency this fee is denominated in — that side's asset.

pricing.fees.amount

string

required

Fee amount, in asset.

pricing.source

object

Economics for the source side, denominated in the source asset.

Hide child attributes

pricing.source.asset

string

Currency these amounts are in. Same as the side's instrument asset, repeated here so pricing is self-contained.

pricing.source.amountGross

string

Amount on this side before fees are applied.

pricing.source.amountNet

string

Amount after fees: what is actually pulled from a source, or delivered to a destination. Identity: amountNet = amountGross − Σ fees(side) (this side's entries in Pricing.fees).

pricing.destination

object

Economics for the destination side, denominated in the destination asset.

Hide child attributes

pricing.destination.asset

string

Currency these amounts are in. Same as the side's instrument asset, repeated here so pricing is self-contained.

pricing.destination.amountGross

string

Amount on this side before fees are applied.

pricing.destination.amountNet

string

Amount after fees: what is actually pulled from a source, or delivered to a destination. Identity: amountNet = amountGross − Σ fees(side) (this side's entries in Pricing.fees).

pricing.exchangeRate

string

Mid-market rate between source and destination assets. Identity: source.amountNet × exchangeRate = destination.amountGross.

pricing.fixedAmountSide

enum<string>

The side you set amount on when creating the quote. OMS calculated the other side.

Available options:

source,

destination

When true, OMS absorbs the destination gas cost. Currently always true.

Gas absorbed by the developer when sponsorGas is true. Currently always 0.00.

tracking

object[]

required

Every rail identifier assigned to this transaction — blockchain tx hashes and Fedwire/SWIFT references (uetr, imad, endToEndId, instructionId) today; ACH/cash rail references planned. Ordered oldest-first by leg; within one leg the entries follow a fixed scheme order, not the moment each identifier was assigned. A re-driven wire payout replaces its previous wire's identifiers in place rather than appending them. [] until the first identifier is assigned.

Hide child attributes

tracking.scheme

string

required

Identifier kind. Emitted today: "txHash" (on-chain hash), "uetr", "imad", "endToEndId", "instructionId" (Fedwire/SWIFT rail identifiers). OPEN — clients must tolerate an unrecognised scheme. tracking is an ordered list, not a set: no combination of fields is unique. The same scheme repeats once per leg that carries such an identifier (a fiat-in → fiat-out payment has a different uetr on source and on destination) and again for each superseded attempt that survives as its own leg. Iterate it; do not index it.

tracking.value

string

required

The identifier itself, verbatim as assigned by the rail/vendor.

tracking.leg

enum<string>

required

Which leg of the transaction this identifier belongs to.

Available options:

source,

destination,

return

tracking.network

string

Network the identifier was assigned on (e.g. "polygon", "ach", "swift") — same vocabulary as instrument network fields. Absent when the identifier is not network-scoped.

tracking.assignedBy

string

The operator or partner that assigned this identifier, when known — e.g. erebor, coinme. Open — treat the string as free-form rather than a fixed set. Absent when the assigner is not resolvable.

tracking.url

string

Deep link to view this identifier on the rail's own explorer, when one is known.

sourceToDestination

enum<string>

Corridor composite derived from the two sides.

Available options:

cryptoToCrypto,

cryptoToCash,

cryptoToFiatAccount,

cashToCrypto,

fiatAccountToCrypto,

fiatAccountToFiatAccount

customer

object

Display-safe summary of the owning customer (customer.id equals customerId) — lets a list row render without a second request.

Hide child attributes

customer.id

string

required

The OMS customer id (cst_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

customer.name

string

required

Customer display name.

estimatedArrival

string<date-time>

Estimated completion time. Present when the destination rail has a predictable settlement time (e.g. bank payouts and some crypto legs); null otherwise.

error

object

Failure detail. Set when the transaction fails; includes refund or recovery state where applicable.

Hide child attributes

error.code

string

required

Machine-readable error code. Never a provider's own code.

error.message

string

required

Human-readable detail. Never names a provider.

error.occurredAt

string<date-time>

required

When the error occurred.

error.recoverable

boolean

required

Whether the failure can be recovered.

error.manualRecovery

object

Populated only for terminal failures with no resolved refund/return path (v0.11).

Hide child attributes

error.manualRecovery.type

enum<string>

Available options:

manualRecovery

error.manualRecovery.custodian

enum<string>

Available options:

ANCHORAGE_SG,

ANCHORAGE_US,

AQUANOW_CA,

B2C2_UK,

B2C2_US,

BITGO_SG,

BITGO_US,

BITSTAMP_US,

BVNK_US,

CIRCLE_FR,

CIRCLE_US,

CITIBANK_US,

COINBASE_US,

COINSMART_CA,

COPPER_CH,

COPPER_UK,

CUMBERLAND_DRW_LLC_US,

CUMBERLAND_SG,

EREBOR_BANK_US,

FALCONX_US,

FIDELITY_UK,

FIDELITY_US,

FIREBLOCKS_APAC,

FIREBLOCKS_US,

GALAXY_KY,

GEMINI_US,

KRAKEN_BVI,

KRAKEN_EU_IE,

KRAKEN_UK,

KRAKEN_US,

NUBANK_BR,

PAXOS_US,

RAMP_NETWORK_US,

ROBINHOOD_US,

WINTERMUTE_GB,

SELF_HOSTED,

OTHER

error.manualRecovery.instructions

string

error.manualRecovery.referenceFields

object

Reference identifiers for an operator-driven recovery.

Hide child attributes

error.manualRecovery.referenceFields.transactionId

string

Transaction ID (txn_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

error.manualRecovery.referenceFields.sourceTxHash

string

Transaction hash of the originating inbound transfer.

hold

Information requested · object

The hold blocking this transaction while status is awaitingAction. Retained after it clears, with resolvedAt set and required false, so the reason stays visible. Absent if the transaction has never been held.

Information requested
Sender attribution
Deposit address frozen
Deposit address inactive

Hide child attributes

hold.required

boolean

required

Whether the hold is still blocking; false once resolved.

hold.type

enum<string>

required

Type discriminator.

Available options:

informationRequested

hold.instructions

string

required

Human-readable statement of what is needed, safe to surface to the developer. Free text — do not parse it.

hold.requestedFrom

string

required

Who the information is needed from. Today either customer (the end user, reached through you) or developer (you, the integrator). Open vocabulary — tolerate a value you do not recognise.

hold.since

string<date-time>

When the hold started.

hold.deadline

string<date-time>

Deadline to resolve before timeout.

hold.resolvedAt

string<date-time> | null

When the hold was resolved. Absent while the hold is outstanding.

hold.customerId

string | null

The customer the request concerns (cst_ prefix), when it is about a specific customer. Absent otherwise.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$

metadata

object

Free-form key-value pairs supplied at creation or update.

Hide child attributes

metadata.{key}

string

createdAt

string<date-time>

When the transaction was created.

updatedAt

string<date-time>

When the transaction was last updated.

expiresAt

string<date-time>

Expiry of the transaction's actionable window: present on auto-created transactions and on cash payouts (the pickup-code expiry), and retained after completion for audit. Null for other quote-initiated transactions.

projectId

string

The owning project. Populated only on the cross-project admin endpoints (e.g. GET /admin/transactions/redrivable) so operators can tell which project a stranded transaction belongs to. Omitted on partner endpoints, where the project is implicit from the auth token.

Pattern: ^prj_.+$

Overview

Move money

Routes

External Payment Methods

Platform

Execute a transaction (send)

Authorizations

Headers

Body

Response