Submit signed burn intents for withdrawal

curl --request POST \
  --url https://xreserve-api-testnet.circle.com/v1/withdraw \
  --header 'Content-Type: application/json' \
  --data '
{
  "batches": [
    {
      "burnIntents": [
        {
          "maxBlockHeight": "1000000",
          "maxFee": "100000",
          "spec": {
            "version": 1,
            "sourceDomain": 0,
            "destinationDomain": 1,
            "sourceContract": "0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6",
            "destinationContract": "0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
            "sourceToken": "0x000000000000000000000000c2d8b55f8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c",
            "destinationToken": "0x000000000000000000000000d3e9c66f9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d",
            "sourceDepositor": "0x000000000000000000000000e4fad77fadadadadadadadadadadadadadadadad",
            "destinationRecipient": "0x000000000000000000000000f5abc88abebebebebebebebebebebebebebebebe",
            "sourceSigner": "0x000000000000000000000000a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
            "destinationCaller": "0x000000000000000000000000b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
            "value": "1000000",
            "salt": "0xc3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
            "hookData": {
              "remoteDomain": 10001,
              "remoteDepositor": "0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6",
              "remoteToken": "0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
              "forwardingContractAddress": "0x0000000000000000000000000000000000000000",
              "forwardingCalldata": "0x"
            }
          }
        }
      ],
      "burnSignatures": [
        "<string>"
      ],
      "burnTxId": "<string>",
      "useCircleForwarding": true
    }
  ]
}
'

[
  {
    "withdrawalId": "6149dc3d-71bf-4d57-8cc1-5e2d4c0a8e70",
    "burnTxId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "status": "created",
    "useCircleForwarding": true,
    "transferSpecHashes": [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ],
    "attestationPayload": "<string>",
    "attestation": "<string>",
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "failureReason": "verification_failed"
  }
]

POST

withdraw

curl --request POST \
  --url https://xreserve-api-testnet.circle.com/v1/withdraw \
  --header 'Content-Type: application/json' \
  --data '
{
  "batches": [
    {
      "burnIntents": [
        {
          "maxBlockHeight": "1000000",
          "maxFee": "100000",
          "spec": {
            "version": 1,
            "sourceDomain": 0,
            "destinationDomain": 1,
            "sourceContract": "0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6",
            "destinationContract": "0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
            "sourceToken": "0x000000000000000000000000c2d8b55f8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c",
            "destinationToken": "0x000000000000000000000000d3e9c66f9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d",
            "sourceDepositor": "0x000000000000000000000000e4fad77fadadadadadadadadadadadadadadadad",
            "destinationRecipient": "0x000000000000000000000000f5abc88abebebebebebebebebebebebebebebebe",
            "sourceSigner": "0x000000000000000000000000a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
            "destinationCaller": "0x000000000000000000000000b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
            "value": "1000000",
            "salt": "0xc3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
            "hookData": {
              "remoteDomain": 10001,
              "remoteDepositor": "0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6",
              "remoteToken": "0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
              "forwardingContractAddress": "0x0000000000000000000000000000000000000000",
              "forwardingCalldata": "0x"
            }
          }
        }
      ],
      "burnSignatures": [
        "<string>"
      ],
      "burnTxId": "<string>",
      "useCircleForwarding": true
    }
  ]
}
'

[
  {
    "withdrawalId": "6149dc3d-71bf-4d57-8cc1-5e2d4c0a8e70",
    "burnTxId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "status": "created",
    "useCircleForwarding": true,
    "transferSpecHashes": [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    ],
    "attestationPayload": "<string>",
    "attestation": "<string>",
    "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "failureReason": "verification_failed"
  }
]

Body

application/json

Contains signed burn intents to submit for withdrawal.

batches

object[]

required

Array of burn intent batches to submit, up to five per request.

Required array length: 1 - 5 elements

Show child attributes

batches.burnIntents

object[]

required

An array of burn intents. Can be either a single burn intent or a burn intent set.

Required array length: 1 - 10 elements

Show child attributes

batches.burnIntents.maxBlockHeight

string

required

The maximum block height at which the burn intent is valid.

Example:

"1000000"

batches.burnIntents.maxFee

string

required

The maximum fee allowed for the burn intent in the smallest token unit.

Example:

"100000"

batches.burnIntents.spec

object

required

Contains transfer specifications for a withdrawal.

Show child attributes

batches.burnIntents.spec.version

integer

required

Transfer specification version.

Example:

1

batches.burnIntents.spec.sourceDomain

integer

required

Source domain ID.

Example:

0

batches.burnIntents.spec.destinationDomain

integer

required

Destination domain ID.

Example:

1

batches.burnIntents.spec.sourceContract

string

required

Source contract address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6"

batches.burnIntents.spec.destinationContract

string

required

Destination contract address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7"

batches.burnIntents.spec.sourceToken

string

required

Source token address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000c2d8b55f8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c8c"

batches.burnIntents.spec.destinationToken

string

required

Destination token address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000d3e9c66f9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d9d"

batches.burnIntents.spec.sourceDepositor

string

required

Source depositor address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000e4fad77fadadadadadadadadadadadadadadadad"

batches.burnIntents.spec.destinationRecipient

string

required

Destination recipient address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000f5abc88abebebebebebebebebebebebebebebebe"

batches.burnIntents.spec.sourceSigner

string

required

Source signer address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

batches.burnIntents.spec.destinationCaller

string

required

Destination caller address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1"

batches.burnIntents.spec.value

string

required

The transfer amount in the smallest token unit.

Example:

"1000000"

batches.burnIntents.spec.salt

string

required

Random salt that ensures uniqueness as a 32-byte hexadecimal string.

Example:

"0xc3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4"

batches.burnIntents.spec.hookData

object

required

Contains structured hook data for withdrawals, including forwarding and remote chain information.

Show child attributes

batches.burnIntents.spec.hookData.remoteDomain

integer

required

Remote chain domain identifier.

Example:

10001

batches.burnIntents.spec.hookData.remoteDepositor

string

required

Remote depositor address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000a0b86a33e6b6b6b6b6b6b6b6b6b6b6b6b6b6b6b6"

batches.burnIntents.spec.hookData.remoteToken

string

required

Remote token address as a 32-byte hexadecimal string.

Example:

"0x000000000000000000000000b1c97a44e7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7"

batches.burnIntents.spec.hookData.forwardingContractAddress

string

required

Forwarding contract address as a 20-byte hexadecimal string. If you are not forwarding funds, set to 0x0.

Example:

"0x0000000000000000000000000000000000000000"

batches.burnIntents.spec.hookData.forwardingCalldata

string

required

Forwarding call data. If you are forwarding funds, set to 0x + a 4-byte function selector + optional data. If not forwarding, set to 0x.

Example:

"0x"

batches.burnSignatures

string[]

required

An array of signatures for the burn intents. Multiple signatures are needed to meet the multi-sig threshold.

Minimum array length: 2

batches.burnTxId

string

required

The transaction hash of the burn transaction on the remote chain.

batches.useCircleForwarding

boolean

required

Indicates whether Circle should forward the transaction and release funds on either a CCTP supported blockchain or another remote blockchain.

Response

Successfully created withdrawal records.

withdrawalId

string<uuid>

required

The unique identifier of the withdrawal group.

Example:

"6149dc3d-71bf-4d57-8cc1-5e2d4c0a8e70"

burnTxId

string

required

The transaction ID of the burn on the remote network.

Example:

"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"

status

enum<string>

required

The status of the withdrawal.

'created': The withdrawal has been created but the burn transaction on the remote network has not been verified yet.
'verified': The burn transaction on the remote network has been successfully verified. The attestation is available but has been submitted on chain yet.
'confirmed': The attestation has been submitted onchain but the transaction has not been finalized yet.
'finalized': The transaction has been successfully finalized. This state is terminal.
'expired': The attestation expired before it was used. This state is terminal and can be retried.
'failed': The verification failed. The withdrawal cannot proceed. This state is terminal and cannot be retried.

Available options:

created,

verified,

confirmed,

finalized,

expired,

failed

useCircleForwarding

boolean

required

Indicates whether Circle should forward the transaction and release funds on either a CCTP supported blockchain or another remote blockchain.

Example:

true

transferSpecHashes

string[]

required

List of transfer specification hashes for all withdrawal intents in the group.

Example:

[
  "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
]

attestationPayload

string

The full attestation payload.

attestation

string

The xReserve attestation signature.

transactionHash

string

The hash of forwarded transaction.

Example:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

failureReason

string

The reason for failure. Returned when the status is 'failed'.

Example:

"verification_failed"

Prepare a withdrawal request

Get withdrawal status