> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primevault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace a Transaction

> Replace a submitted transaction on a supported chain, if it doesn't already have an active replacement.

**POST** `/api/external/transactions/replace_transaction/`

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

## Request body

<ParamField body="transactionId" type="string" required>
  The ID of the transaction to replace.
</ParamField>

## Response

```json theme={null}
{
  "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
}
```

## Approve the transaction

New transactions return `status: "PENDING"` and wait for approval. [Get the approval message](/approvals/get-approval-message) for the transaction `id`, sign it with your API user's key, then [submit the approval](/approvals/submit-approval-action). See [Approvals](/approvals/overview).

With the SDK, call `approveChangeRequest({ entityId: transaction.id, action: "approve" })` after this call.

<RequestExample dropdown>
  ```json Request example theme={null}
  {
    "transactionId": "transaction_123"
  }
  ```

  ```bash cURL theme={null}
  # Sample only. Generate a new signed token for each request
  # (see Authentication). Tokens expire after 120 seconds.
  curl --request POST \
    --url "https://api.primevault.com/api/external/transactions/replace_transaction/" \
    --header "Authorization: Bearer <signed JWT>" \
    --header "Api-Key: <API key>" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data '{"transactionId": "transaction_123"}'
  ```

  ```typescript JavaScript SDK theme={null}
  replaceTransaction(request: {
    transactionId: string;
  }): Promise<Transaction>
  ```
</RequestExample>

<ResponseExample>
  ```json JSON example theme={null}
  {
    "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
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.