Accelerate a stuck transaction

curl --request POST \
  --url https://api.circle.com/v1/cpn/payments/{paymentId}/transactions/accelerate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
}
'

{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "status": "PENDING",
    "expireDate": "2023-01-01T12:04:05Z",
    "senderAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "senderAccountType": "EOA",
    "blockchain": "ETH-SEPOLIA",
    "amount": {
      "amount": "110.270000",
      "currency": "USDC"
    },
    "destinationAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "messageType": "EIP3009",
    "messageToBeSigned": {},
    "failureReason": "FAILED_ONCHAIN",
    "estimatedFee": {
      "type": "EIP1559",
      "payload": {
        "gasLimit": "21000",
        "maxFeePerGas": "5935224468",
        "maxPriorityFeePerGas": "1022783914"
      }
    },
    "signedTransaction": "AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpzlAhqqen7eyTe0KQ3w+9NS4E+7sscb+Cr...",
    "transactionHash": "2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"
  }
}

Transactions

Accelerate a stuck transaction

Accelerate a transaction based on the payment ID. It should be used when a transaction associated with the payment is broadcasted but not confirmed for a long period of time (i.e 10 minutes). This is usually due to gas fees being too low and not picked up by any miner/validator.
The /accelerate endpoint essentially creates another transaction with the same params as the broadcasted transaction. If multiple broadcasted transactions exist, it will use the newest created one. Afterwards, OFI can sign with a higher gas fee and submit via /submit endpoint to accelerate blockchain confirmation.
Requirements for using this endpoint:
- No COMPLETED transaction exist for the payment (otherwise onchain transaction has completed)
- No CREATED transaction exist for the payment, otherwise OFI should sign that transaction and submit
- No PENDING transaction exist for the payment, otherwise OFI should wait for transaction to be broadcasted
In another word, all existing transaction for the payment should either be FAILED (which is no longer effective) or BROADCASTED (which means they are stuck onchain and not confirmed)

POST

cpn

payments

{paymentId}

transactions

accelerate

Accelerate a stuck transaction

curl --request POST \
  --url https://api.circle.com/v1/cpn/payments/{paymentId}/transactions/accelerate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
}
'

{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "status": "PENDING",
    "expireDate": "2023-01-01T12:04:05Z",
    "senderAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "senderAccountType": "EOA",
    "blockchain": "ETH-SEPOLIA",
    "amount": {
      "amount": "110.270000",
      "currency": "USDC"
    },
    "destinationAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "messageType": "EIP3009",
    "messageToBeSigned": {},
    "failureReason": "FAILED_ONCHAIN",
    "estimatedFee": {
      "type": "EIP1559",
      "payload": {
        "gasLimit": "21000",
        "maxFeePerGas": "5935224468",
        "maxPriorityFeePerGas": "1022783914"
      }
    },
    "signedTransaction": "AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpzlAhqqen7eyTe0KQ3w+9NS4E+7sscb+Cr...",
    "transactionHash": "2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"
  }
}

Authorizations

Authorization

string

header

required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Path Parameters

paymentId

string<uuid>

required

The payment id created previously. System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

Body

application/json

Accelerate a broadcasted transaction, which is stuck in mempool due to low gas fee, by broadcasting the same transaction with high gas fee.

idempotencyKey

string<uuid>

required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. To create a UUIDv4 go to uuidgenerator.net. If the same key is reused, it will be treated as the same request and the original response will be returned.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

Response

Transaction accelerated successfully.

data

object

required

Response schema for a blockchain transaction containing details about the transaction amount, addresses, fees, and status

Show child attributes

data.id

string<uuid>

required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

data.paymentId

string<uuid>

required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

data.status

enum<string>

required

Lifecycle status of a transaction

Available options:

CREATED,

PENDING,

BROADCASTED,

COMPLETED,

FAILED

Example:

"PENDING"

data.expireDate

string<date-time>

required

Date and time when the resource expires

Example:

"2023-01-01T12:04:05Z"

data.senderAddress

string

required

A blockchain address that can be used to send or receive transactions on a blockchain network.

Example:

"0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c"

data.senderAccountType

enum<string>

required

The type of blockchain account (currently supports only EOA - Externally Owned Account).

Available options:

EOA

Example:

"EOA"

data.blockchain

enum<string>

required

Supported blockchain networks

Available options:

SOL,

MATIC,

ETH,

SOL-DEVNET,

MATIC-AMOY,

ETH-SEPOLIA

Example:

"ETH-SEPOLIA"

data.amount

object

required

Represents an amount of cryptocurrency, including both the numerical amount and the specific cryptocurrency type.

Show child attributes

data.amount.amount

string

Example:

"110.270000"

data.amount.currency

enum<string>

Supported cryptocurrencies

Available options:

USDC

Example:

"USDC"

Example:

{
  "amount": "110.270000",
  "currency": "USDC"
}

data.destinationAddress

string

required

A blockchain address that can be used to send or receive transactions on a blockchain network.

Example:

"0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c"

data.messageType

enum<string>

required

Transaction message type

Available options:

EIP3009,

SOLANA

Example:

"EIP3009"

data.messageToBeSigned

object

required

The message to be signed by OFI on Circle supported EVM chains and Solana (A EVM EOA message or a SOL message).

data.failureReason

enum<string>

Possible reasons for transaction failure

Available options:

CPN_PAYMENT_EXPIRED,

SIGNED_TRANSACTION_EXPIRED,

NONCE_TOO_LOW,

NONCE_TOO_HIGH,

INSUFFICIENT_TOKEN_BALANCE,

INSUFFICIENT_GAS_BALANCE,

GAS_PRICE_TOO_LOW,

OUT_OF_GAS,

TX_REPLACEMENT_FAILED,

SOL_TX_ALREADY_IN_CACHE,

TX_ALREADY_CONFIRMED,

FAILED_ONCHAIN,

SOL_BLOCKHASH_EXPIRED,

TRANSACTION_EXPIRED,

BROADCAST_FAILED,

RELAY_FAILED,

UNKNOWN_REASON

Example:

"FAILED_ONCHAIN"

data.estimatedFee

object

The suggested fee is provided to guide the OFI in constructing and signing the transaction object for submission.

Option 1
Option 2

Show child attributes

data.estimatedFee.type

enum<string>

Available options:

EIP1559

data.estimatedFee.payload

object

Payload containing EIP-1559 fee configuration parameters for Ethereum transactions

Show child attributes

data.estimatedFee.payload.gasLimit

string

Maximum amount of gas units that can be used for the transaction

Example:

"21000"

data.estimatedFee.payload.maxFeePerGas

string

Maximum total fee per gas (base fee + priority fee) in wei

Example:

"5935224468"

data.estimatedFee.payload.maxPriorityFeePerGas

string

Maximum priority fee per gas (tip to miners) in wei

Example:

"1022783914"

data.signedTransaction

string

Signed transaction. Base64 encoded for NEAR and Solana chains. Hex encoded for EVM chains.

Example:

"AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpzlAhqqen7eyTe0KQ3w+9NS4E+7sscb+Cr..."

data.transactionHash

string

Unique identifier assigned to a blockchain transaction when it is broadcast to the network

Example:

"2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"

Submit a signed transaction for broadcast

Create a transaction (V2)

API Overview

Circle Payments Network

Accelerate a stuck transaction

Authorizations

Path Parameters

Body

Response