Create a challenge for a transfer

Generates a challenge for initiating an on-chain digital asset transfer from a specified user-controlled wallet

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.

Headers

X-User-Token · string · required

Unique system generated JWT session token for specific user.

X-Request-Id · string

Developer-provided parameter used to identify this request. Useful when communicating with Circle Support.

Example:

"2adba88e-9d63-44bc-b975-9b6ae3440dde"

Body

application/json

Create transaction for end user request

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"

destinationAddress · string · required

Blockchain generated unique identifier, associated with wallet (account), smart contract or other blockchain objects.

Example:

"0xca9142d0b9804ef5e239d3bc1c7aa0d1c74e7350"

walletId · string<uuid> · required

Unique system generated identifier of the wallet. Required when sourceAddress and blockchain are not provided. Mutually exclusive with sourceAddress and blockchain. For contract deploys this wallet ID will be used as the source.

Example:

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

amounts · string[]

Transfer amounts in decimal number format, at least one element is required for transfer. For ERC721 token transfer, the amounts field is required to be ["1"] (array with "1" as the only element).

Minimum length: 1

Example:

["6.62607015"]

feeLevel · enum<string>

A dynamic blockchain fee level setting (LOW, MEDIUM, or HIGH) that will be used to pay gas for the transaction. Calculated based on network traffic, supply of validators, and demand for transaction verification. Cannot be used with gasPrice, priorityFee, or maxFee. Estimates for each fee level can be obtained through the POST /transactions/transfer/estimateFee API.

Available options:

LOW,

MEDIUM,

HIGH

Example:

"MEDIUM"

gasLimit · string

The maximum units of gas to use for the transaction. Required if feeLevel is not provided. Estimates for this limit can be obtained through the POST /transactions/transfer/estimateFee API. GasLimit override (only supported for EOA wallets): Using gasLimit together with feeLevel, the provided gasLimit is required to be greater or equal to feeLevel estimation and will override the estimation's gasLimit.

Example:

"21000"

gasPrice · string

For blockchains without EIP-1559 support, the maximum price of gas, in gwei, to use per each unit of gas (see gasLimit). Requires gasLimit. Cannot be used with feeLevel, priorityFee, or maxFee. Estimates for this fee can be obtained through the POST /transactions/transfer/estimateFee API.

maxFee · string

For blockchains with EIP-1559 support, the maximum price per unit of gas (see gasLimit), in gwei. Requires priorityFee, and gasLimit to be present. Cannot be used with feeLevel or gasPrice. Estimates for this fee can be obtained through the POST /transactions/transfer/estimateFee API.

Example:

"5.935224468"

priorityFee · string

For blockchains with EIP-1559 support, the “tip”, in gwei, to add to the base fee as an incentive for validators. Please note that the maxFee and gasLimit parameters are required alongside the priorityFee. The feeLevel and gasPrice parameters cannot be used with the priorityFee. Estimations for this fee can be obtained through the POST /transactions/transfer/estimateFee API.

Example:

"1.022783914"

nftTokenIds · string[]

List of NFT token IDs corresponding with the NFTs to transfer. Batch transfers are supported only for ERC-1155 tokens. The length of NFT token IDs must match the length of amounts.

The NFT token ID.

refId · string

Optional reference or description used to identify the transaction.

Example:

"grouptransaction123"

tokenId · string<uuid>

System generated identifier of the token. Excluded with tokenAddress and tokenBlockchain.

tokenAddress · string

Blockchain address of the transferred token. Empty for native tokens. Excluded with tokenId.

blockchain · enum<string>

Blockchain of the transferred token. Required if tokenId is not provided. The blockchain and tokenId fields are mutually exclusive.

Available options:

ETH,

ETH-SEPOLIA,

AVAX,

AVAX-FUJI,

MATIC,

MATIC-AMOY,

SOL,

SOL-DEVNET,

ARB,

ARB-SEPOLIA,

UNI,

UNI-SEPOLIA,

BASE,

BASE-SEPOLIA,

OP,

OP-SEPOLIA,

APTOS,

APTOS-TESTNET

Example:

"MATIC-AMOY"

Response

200

application/json

The challenge for the transfer was successfully created

data · object

Show child attributes