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

Swaps

Execute Route Swap

This endpoint performs a multi-hop swap through a sequence of liquidity pools, allowing users to exchange assets that may not have direct trading pairs. Each hop in the route represents a swap through a different pool.

Route Swap Process

User deposits input asset via Spark transfer
Submit route swap request with transfer proof and hop sequence
System executes swaps sequentially through each pool
Each hop’s output becomes the next hop’s input
Final output is sent to the user
If any hop fails, the entire route is reverted

Multi-Hop Execution

The route is executed atomically:

All hops must succeed or the entire swap fails
Intermediate assets are handled internally
Only initial deposit and final output involve user transfers
Each hop maintains its own slippage protection

Route Validation

Before execution, the system validates:

Route contains 1-4 hops (maximum complexity limit)
All pools in the route exist and are active
Asset pairs match between consecutive hops
Sufficient liquidity exists in each pool
Total slippage remains within tolerance

Fee Structure

Fees are applied at each hop:

LP Fees: Paid to liquidity providers of each pool
Integrator Fees: Optional fees for route providers
Host Fees: Platform fees for each pool’s host
Fees compound through the route (each hop’s fee reduces next hop’s input)

Slippage Protection

Two levels of slippage protection:

Per-hop protection: Each pool enforces its own price limits
Route-wide protection: Overall output must meet minimum requirement
max_route_slippage_bps: Maximum acceptable deviation for entire route

Authentication

Requires a valid JWT bearer token. The token’s public key must match the user_public_key in the request. The request must be signed with the user’s private key.

Arguments

user_public_key - Public key of the user executing the swap
hops - Ordered list of pools and assets for the route
initial_spark_transfer_id - Spark transfer proof for input asset
input_amount - Amount of initial asset to swap
max_route_slippage_bps - Maximum slippage for entire route
nonce - Unique value for replay protection
signature - Request signature for verification
integrator_fee_rate_bps - Optional default integrator fee
integrator_public_key - Optional integrator identifier

Returns

200 OK with route swap details if successful
400 Bad Request if validation fails or route cannot be executed
401 Unauthorized if authentication or signature verification fails
500 Internal Server Error if route execution fails

POST

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.

Show child attributes

hops.poolId

string

required

The public key of the liquidity pool for this hop.

Example:

"03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"

hops.assetInAddress

string

required

The public key of the asset being swapped into the pool.

Example:

"03bitcoinassetpubkey0000000000000000000000000000000000000000000000"

hops.assetOutAddress

string

required

The public key of the asset being swapped out of the pool.

Example:

"03ethereumassetpubkey1111111111111111111111111111111111111111111111"

hops.hopIntegratorFeeRateBps

integer<uint64> | null

Optional fee in basis points for an integrator on this specific hop.

Required range: x >= 0

Example:

25

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<uint64>

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<uint64> | 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.

flashnetRequestId

string | null

Settlement service request ID for correlation

Example:

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

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<uint64> | null

The amount of the refunded asset.

Required range: x >= 0

refundTransferId

string | null

The unique identifier of the refund transfer on Spark.

Get Pool Swaps

Simulate Route Swap

⌘I

Auth

Clawback

Hosts

Integrators

Liquidity

Status

Pools

Swaps

Execute Route Swap

Route Swap Process

Multi-Hop Execution

Route Validation

Fee Structure

Slippage Protection

Authentication

Arguments

Returns

Authorizations

Body

Response