POST
/
v1
/
swap
Execute Swap
curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amountIn": "100000000",
  "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
  "assetInSparkTransferId": "spark-transfer-uuid-or-hash-for-asset-in",
  "assetOutAddress": "03usdstablecoinpubkey111111111111111111111111111111111111111111111",
  "integratorPublicKey": "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
  "maxSlippageBps": "50",
  "nonce": "unique-swap-nonce-123",
  "poolId": "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
  "signature": "3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3",
  "totalIntegratorFeeRateBps": "100",
  "userPublicKey": "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"
}'
{
"accepted": false,
"error": "Insufficient liquidity in pool",
"refundTransferId": "spark-transfer-refund-456",
"refundedAmount": 100000000,
"refundedAssetAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
"requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Swap execution details including assets, amounts, and authentication

Request body for executing a swap on an AMM pool.

Swaps allow users to exchange one asset for another through a liquidity pool. The swap is executed atomically and the result is returned immediately.

userPublicKey
string
required

Public key of the user executing the swap. Must match the authenticated user's public key.

Example:

"02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"

poolId
string
required

LP public key of the pool to swap through. The pool must be active and have sufficient liquidity.

Example:

"03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"

assetInAddress
string
required

Public key of the asset being provided by the user. Must be one of the two assets in the selected pool.

Example:

"03bitcoinassetpubkey0000000000000000000000000000000000000000000000"

assetOutAddress
string
required

Public key of the asset the user wants to receive. Must be the other asset in the selected pool.

Example:

"03usdstablecoinpubkey111111111111111111111111111111111111111111111"

amountIn
integer
required

Amount of input asset to swap, in its smallest unit. Must be positive and within the pool's liquidity capacity.

Required range: x >= 0
Example:

100000000

maxSlippageBps
integer
required

Optional maximum slippage tolerance in basis points (BPS). If set, can override min_amount_out. 1 BPS = 0.01%, so 50 BPS = 0.5%.

Required range: x >= 0
Example:

50

minAmountOut
integer
required

Optional mininimum amount out If set to none, 0

Required range: x >= 0
Example:

100000000

assetInSparkTransferId
string
required

Spark network transfer ID proving the deposit of input asset. Must be a valid, confirmed transfer to the pool's address.

Example:

"spark-transfer-uuid-or-hash-for-asset-in"

nonce
string
required

Unique nonce for replay protection. Each swap must use a unique nonce that hasn't been used before.

Example:

"unique-swap-nonce-123"

totalIntegratorFeeRateBps
integer
required

Total integrator fee the user accepts to pay.

Required range: x >= 0
Example:

100

integratorPublicKey
string
required

Integrator public key.

Example:

"03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"

signature
string
required

Hex-encoded secp256k1 signature of the request. Must be signed by the private key corresponding to user_public_key.

Example:

"3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3"

Response

Swap executed successfully

Clean response for a successfully executed swap operation

requestId
string
required

User-friendly request ID for tracking

Example:

"01HJZKFABCDEFGHJKLMNPQRSTVW"

accepted
boolean
required

Whether the swap was accepted or rejected

Example:

true

amountOut
integer | null

Amount received from the swap (populated if accepted)

Required range: x >= 0
Example:

"495000"

feeAmount
integer | null

Fee paid for the swap (populated if accepted)

Required range: x >= 0
Example:

"5000"

executionPrice
string | null

Execution price as a string (populated if accepted)

Example:

"0.00495000"

assetOutAddress
string | null

Asset received by the user (populated if accepted)

Example:

"03usdstablecoinpubkey111111111111111111111111111111111111111111111"

assetInAddress
string | null

Asset sent by the user (populated if accepted)

Example:

"03bitcoinassetpubkey0000000000000000000000000000000000000000000000"

outboundTransferId
string | null

Spark transfer ID for receiving asset (populated if accepted)

Example:

"spark-transfer-out-123"

error
string | null

User-friendly error message (populated if rejected)

Example:

"Insufficient liquidity in pool"

refundedAssetAddress
string | null

Refunded asset (populated if rejected)

Example:

"03bitcoinassetpubkey0000000000000000000000000000000000000000000000"

refundedAmount
integer | null

Refunded amount (populated if rejected)

Required range: x >= 0
Example:

"100000000"

refundTransferId
string | null

Spark transfer ID for refund (populated if rejected)

Example:

"spark-transfer-refund-456"