Skip to main content
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<uint64>
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<uint64>
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

​
flashnetRequestId
string | null

Settlement service request ID for correlation

Example:

"018D5E56-9D80-7890-A1B2-C3D4E5F6G7H8"

​
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"