POST
/
v1
/
route-swap
Execute Route Swap
curl --request POST \
  --url https://api.amm.flashnet.xyz/v1/route-swap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "hops": [
    {
      "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
      "assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "hopIntegratorFeeRateBps": "50",
      "poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
    },
    {
      "assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
      "assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
      "hopIntegratorFeeRateBps": "50",
      "poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
    }
  ],
  "initialSparkTransferId": "spark-transfer-uuid-or-hash-for-initial-deposit",
  "inputAmount": "100000000",
  "integratorFeeRateBps": "100",
  "integratorPublicKey": "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
  "maxRouteSlippageBps": "200",
  "minAmountOut": "100000000",
  "nonce": "unique-route-swap-nonce-456",
  "signature": "3045022100a7e5d4f8b2c9a1e6f0d5b8c4a9e7f2d1c8b5a4e9f0d6c5b3a2e1d0c9b8a7f02201f2e3d4c5b6a7980e9f0a1b2c3d4e5f67889a0b1c2d3e4f5a6b7c8d9e0f1a2b3",
  "userPublicKey": "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"
}'
{
"accepted": false,
"error": "Insufficient liquidity in hop 2",
"executionPrice": "0",
"finalOutboundTransferId": "",
"outputAmount": "0",
"refundTransferId": "spark-transfer-refund-999",
"refundedAmount": "100000000",
"refundedAssetPublicKey": "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

Route swap execution details including hop sequence and authentication

Defines the request to execute a swap across a defined route of liquidity pools.

userPublicKey
string
required

The public key of the user initiating the swap. Must match the key in the auth token.

Example:

"02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567"

hops
object[]
required

An ordered sequence of pools and assets that defines the swap route. Must contain 1-4 hops.

Example:
[
{
"assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
"assetOutAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
"hopIntegratorFeeRateBps": "25",
"poolId": "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
},
{
"assetInAddress": "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
"assetOutAddress": "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
"hopIntegratorFeeRateBps": "25",
"poolId": "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
}
]
initialSparkTransferId
string
required

The unique identifier of the Spark transfer for the initial input asset deposit.

Example:

"spark-route-transfer-uuid-123456"

inputAmount
integer
required

The total amount of the input asset to be swapped, in its smallest unit.

Required range: x >= 0
Example:

100000000

maxRouteSlippageBps
integer
required

The maximum acceptable slippage for the entire route, in basis points.

Required range: x >= 0
Example:

200

minAmountOut
integer
required

The minimum amount of the final output asset the user agrees to receive.

Required range: x >= 0
Example:

100000000

nonce
string
required

A unique, user-generated string to prevent replay attacks.

Example:

"unique-route-swap-nonce-789"

signature
string
required

Cryptographic signature of the request payload for verification.

Example:

"3045022100b8c9d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6789012345678901234567890123402207f6e5d4c3b2a1908f7e6d5c4b3a29180706f5e4d3c2b1a0908070605040302010"

integratorFeeRateBps
integer | null

An optional default fee in basis points for the route integrator.

Required range: x >= 0
Example:

50

integratorPublicKey
string | null

The public key of the integrator to receive fees. Required if integrator_fee_rate_bps is set.

Example:

"03integratorpubkey33445566778899aabbccddeeff00112233445566778899aa"

Response

Route swap execution successful

Represents the response after a route swap execution attempt.

requestId
string
required

A unique identifier for the request, for tracing and logging.

accepted
boolean
required

Indicates whether the route swap was accepted for processing.

outputAmount
integer
required

The final amount of the output asset received, in its smallest unit.

Required range: x >= 0
executionPrice
string
required

The effective price of the swap, calculated as output_amount / input_amount.

finalOutboundTransferId
string
required

The unique identifier of the final Spark transfer for the output asset.

error
string | null

If the swap failed, this field contains a description of the error.

refundedAssetAddress
string | null

If the swap failed and a refund was issued, this is the public key of the refunded asset.

refundedAmount
integer | null

The amount of the refunded asset.

Required range: x >= 0
refundTransferId
string | null

The unique identifier of the refund transfer on Spark.