Transactions

15 min

Transactions are the lifecycle record for asset movement, contract execution, staking and delegation, ramps, and foreign-exchange flows.

All amounts are decimal strings. Create calls return a Transaction; its status is the lifecycle source of truth. A successful HTTP response does not imply that the transaction has completed.

Choose a transaction flow

Move between bank money and digital currency: Ramps .

Exchange one fiat currency for another: FX .

Goal	Use
Move a known asset from a known source to a known destination	Transfers
Submit a contract call, stake a resource, or delegate a protocol resource	On-chain Interactions
Request and execute a priced on-ramp, off-ramp, or foreign-exchange route	Ramps & FX

The sections below cover operations shared by every transaction type. Open the corresponding child page for creation requests, request fields, and complete examples.

List transactions

GET /api/external/transactions/?limit={limit}&cursor={cursor}&{filters}

Query parameters

Parameter	Type	Required	Description
limit	number	No	Requested page size. SDK default: 20.
cursor	string \| null	No	Cursor for the next page.
Filters	Record<string, string>	No	Transaction filters such as status, category, vaultId, asset, or externalId when supported.

Request example

{
  "query": {
    "limit": 20,
    "cursor": null,
    "status": "COMPLETED",
    "vaultId": "vault_123"
  }
}

Response

interface TransactionListResponse {
  results: Transaction[];
  nextCursor?: string | null;
  hasNext?: boolean;
}

JSON example

{
  "results": [
    {
      "id": "transaction_123",
      "orgId": "org_456",
      "vaultId": "vault_123",
      "status": "COMPLETED",
      "transactionType": "OUTGOING",
      "category": "TRANSFER",
      "subCategory": "EXTERNAL_TRANSFER",
      "createdAt": "2026-08-04T10:40:00Z",
      "updatedAt": "2026-08-04T10:42:15Z",
      "isDeleted": false,
      "externalId": "invoice-1001",
      "memo": "Vendor payout #1001",
      "source": {
        "type": "VAULT",
        "id": "vault_123",
        "subOrgId": "sub_org_123",
        "name": "Treasury Vault"
      },
      "destination": {
        "type": "CONTACT",
        "id": "contact_456",
        "name": "Operations Wallet",
        "address": "0xAbC1234567890abcdef1234567890abcdef1234",
        "chain": "ETHEREUM"
      },
      "blockChain": "ETHEREUM",
      "asset": "ETH",
      "amount": "0.50",
      "txHash": "0x9f4e6c1b7a2d3e4f",
      "operations": [
        {
          "source": {
            "type": "VAULT",
            "id": "vault_123",
            "subOrgId": "sub_org_123",
            "name": "Treasury Vault"
          },
          "destination": {
            "type": "CONTACT",
            "id": "contact_456",
            "name": "Operations Wallet",
            "address": "0xAbC1234567890abcdef1234567890abcdef1234",
            "chain": "ETHEREUM"
          },
          "balanceChanges": {
            "changes": [
              {
                "party": {
                  "type": "VAULT",
                  "id": "vault_123",
                  "subOrgId": "sub_org_123",
                  "name": "Treasury Vault"
                },
                "asset": "ETH",
                "amount": "-0.50",
                "chain": "ETHEREUM"
              },
              {
                "party": {
                  "type": "CONTACT",
                  "id": "contact_456",
                  "name": "Operations Wallet",
                  "address": "0xAbC1234567890abcdef1234567890abcdef1234",
                  "chain": "ETHEREUM"
                },
                "asset": "ETH",
                "amount": "0.50",
                "chain": "ETHEREUM"
              }
            ]
          },
          "sequence": 1,
          "type": "TRANSFER",
          "status": "COMPLETED"
        }
      ],
      "balanceChanges": {
        "changes": [
          {
            "party": {
              "type": "VAULT",
              "id": "vault_123",
              "subOrgId": "sub_org_123",
              "name": "Treasury Vault"
            },
            "asset": "ETH",
            "amount": "-0.50",
            "chain": "ETHEREUM"
          },
          {
            "party": {
              "type": "CONTACT",
              "id": "contact_456",
              "name": "Operations Wallet",
              "address": "0xAbC1234567890abcdef1234567890abcdef1234",
              "chain": "ETHEREUM"
            },
            "asset": "ETH",
            "amount": "0.50",
            "chain": "ETHEREUM"
          }
        ]
      }
    }
  ],
  "nextCursor": "eyJpZCI6InRyYW5zYWN0aW9uXzEyMyJ9",
  "hasNext": true
}

JavaScript SDK

getTransactions(
  params?: Record<string, string>,
  limit?: number,
  cursor?: string | null,
): Promise<TransactionListResponse>

Retrieve a transaction

GET /api/external/transactions/{transactionId}/

Request example

{
  "path": {
    "transactionId": "transaction_123"
  }
}

Response

{
  "id": "transaction_123",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "COMPLETED",
  "transactionType": "OUTGOING",
  "category": "TRANSFER",
  "subCategory": "EXTERNAL_TRANSFER",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T10:42:15Z",
  "isDeleted": false,
  "externalId": "invoice-1001",
  "memo": "Vendor payout #1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "subOrgId": "sub_org_123",
    "name": "Treasury Vault"
  },
  "destination": {
    "type": "CONTACT",
    "id": "contact_456",
    "name": "Operations Wallet",
    "address": "0xAbC1234567890abcdef1234567890abcdef1234",
    "chain": "ETHEREUM"
  },
  "blockChain": "ETHEREUM",
  "asset": "ETH",
  "amount": "0.50",
  "txHash": "0x9f4e6c1b7a2d3e4f",
  "operations": [
    {
      "source": {
        "type": "VAULT",
        "id": "vault_123",
        "subOrgId": "sub_org_123",
        "name": "Treasury Vault"
      },
      "destination": {
        "type": "CONTACT",
        "id": "contact_456",
        "name": "Operations Wallet",
        "address": "0xAbC1234567890abcdef1234567890abcdef1234",
        "chain": "ETHEREUM"
      },
      "balanceChanges": {
        "changes": [
          {
            "party": {
              "type": "VAULT",
              "id": "vault_123",
              "subOrgId": "sub_org_123",
              "name": "Treasury Vault"
            },
            "asset": "ETH",
            "amount": "-0.50",
            "chain": "ETHEREUM"
          },
          {
            "party": {
              "type": "CONTACT",
              "id": "contact_456",
              "name": "Operations Wallet",
              "address": "0xAbC1234567890abcdef1234567890abcdef1234",
              "chain": "ETHEREUM"
            },
            "asset": "ETH",
            "amount": "0.50",
            "chain": "ETHEREUM"
          }
        ]
      },
      "sequence": 1,
      "type": "TRANSFER",
      "status": "COMPLETED"
    }
  ],
  "balanceChanges": {
    "changes": [
      {
        "party": {
          "type": "VAULT",
          "id": "vault_123",
          "subOrgId": "sub_org_123",
          "name": "Treasury Vault"
        },
        "asset": "ETH",
        "amount": "-0.50",
        "chain": "ETHEREUM"
      },
      {
        "party": {
          "type": "CONTACT",
          "id": "contact_456",
          "name": "Operations Wallet",
          "address": "0xAbC1234567890abcdef1234567890abcdef1234",
          "chain": "ETHEREUM"
        },
        "asset": "ETH",
        "amount": "0.50",
        "chain": "ETHEREUM"
      }
    ]
  }
}

JavaScript SDK

getTransactionById(transactionId: string): Promise<Transaction>

Replace a submitted transaction

POST /api/external/transactions/replace_transaction/

REST request body

{
  "transactionId": "transaction_123"
}

Replacement is accepted only for a SUBMITTED transaction on a chain that supports replacement and when no active replacement already exists.

Response

{
  "id": "transaction_replacement_456",
  "orgId": "org_456",
  "vaultId": "vault_123",
  "status": "PENDING",
  "transactionType": "OUTGOING",
  "category": "TRANSFER",
  "subCategory": "EXTERNAL_TRANSFER",
  "createdAt": "2026-08-04T10:40:00Z",
  "updatedAt": "2026-08-04T11:30:00Z",
  "isDeleted": false,
  "externalId": "invoice-1001-replacement",
  "memo": "Vendor payout #1001",
  "source": {
    "type": "VAULT",
    "id": "vault_123",
    "subOrgId": "sub_org_123",
    "name": "Treasury Vault"
  },
  "destination": {
    "type": "CONTACT",
    "id": "contact_456",
    "name": "Operations Wallet",
    "address": "0xAbC1234567890abcdef1234567890abcdef1234",
    "chain": "ETHEREUM"
  },
  "blockChain": "ETHEREUM",
  "asset": "ETH",
  "amount": "0.50",
  "nonce": 42
}

JavaScript SDK

replaceTransaction(request: {
  transactionId: string;
}): Promise<Transaction>