Docs

Swap API

Public API reference for swap quotes, order creation, and order tracking.

Swap API

This document describes the public Swap API for website and external integrations.

All endpoints in this document are published under the following namespace:

/external/swap/*

Base URL

https://back.2aml.com/external/swap

Authentication

The Swap API does not require JWT authentication.

Recommended headers:

Content-Type: application/json
Accept: application/json

Optional attribution header:

x-fingerprint: fp_browser_or_device_identifier

If x-fingerprint is sent in both the request header and the request body, the body value takes precedence.

General Conventions

  • All request amounts must be sent as strings.
  • Quote responses return numeric amounts.
  • Order responses return stored order amounts as strings.
  • All timestamps are returned as ISO 8601 strings.
  • orderId is the canonical identifier for tracking an order.

Integration Flow

Recommended integration sequence:

  1. Call GET /currencies.
  2. Call GET /pairs.
  3. Call GET /min-amount or GET /range.
  4. Call GET /estimated-amount.
  5. Optionally call GET /network-fee.
  6. Call GET /validate/address.
  7. Call POST /orders.
  8. Poll GET /orders/:orderId until a terminal status is reached.

Optional utility endpoint:

  • GET /markets/estimate for display-only market conversion.

Request Modes

Direct Requests

Use type=direct when the source amount is known in advance.

  • Send fromAmount.
  • Do not rely on toAmount as the input field.

Reverse Requests

Use type=reverse when the destination amount is known in advance.

  • Send toAmount.
  • Reverse requests are supported only in fixed-rate flow.

Fixed-Rate Quotes

If a fixed-rate quote returns rateId, preserve it exactly and send it unchanged to POST /orders.

Integration rules:

  • treat rateId as an opaque value
  • do not parse it
  • do not trim it
  • do not assume a fixed format or length

Refund Address

Some fixed-rate requests can require refundAddress.

Integration rule:

  • if your integration supports fixed-rate execution, support refundAddress in both quote and create flows

Order Status

StatusTerminalDescription
awaiting_depositNoThe order is created and payment instructions are available.
confirmingNoA deposit has been detected and is awaiting confirmation.
processingNoThe swap is being processed.
sendingNoThe payout transfer is in progress.
completedYesThe order completed successfully.
failedYesThe order failed.
refundedYesThe order was refunded.
pending_supportYesThe order cannot continue automatically through this API.

Order display rules:

  • show payment instructions only while payment !== null
  • stop polling after a terminal status is returned
  • always branch on status, not on free-text message content

Endpoint Summary

MethodPathPurpose
GET/currenciesList supported swap currencies and networks
GET/pairsList supported currency routes
GET/min-amountReturn the minimum supported amount for a route
GET/rangeReturn the minimum and maximum supported amount for a route
GET/estimated-amountReturn a quote estimate
GET/network-feeReturn estimated network fees
GET/markets/estimateReturn a display-oriented market conversion estimate
GET/validate/addressValidate the destination payout address
POST/ordersCreate a swap order
GET/orders/:orderIdGet order status by orderId

1. List Currencies

Returns the supported currency and network combinations for swap.

Endpoint

GET /currencies

Query Parameters

FieldTypeRequiredDescription
activestringNoIf true, returns only active assets.
flow`'standard''fixed-rate'`No
buystringNoOptional availability filter.
sellstringNoOptional availability filter.

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/currencies?active=true'

Example Response

[
  {
    "currency": "btc",
    "network": "btc",
    "name": "Bitcoin",
    "supportsFixedRate": true,
    "destinationExtraIdSupported": false,
    "destinationExtraIdRequired": false,
    "isStable": false,
    "isFiat": false,
    "tokenContract": null
  }
]

Response Fields

FieldTypeDescription
currencystringAsset ticker.
networkstringNetwork identifier to use in later requests.
namestringDisplay name.
supportsFixedRatebooleanWhether fixed-rate mode is available.
destinationExtraIdSupportedbooleanWhether a destination extra id can be submitted.
destinationExtraIdRequiredbooleanWhether a destination extra id is required.
isStablebooleanWhether the asset is marked as stable.
isFiatbooleanWhether the asset is fiat.
tokenContract`stringnull`

2. List Pairs

Returns supported swap routes.

Endpoint

GET /pairs

Query Parameters

FieldTypeRequiredDescription
fromCurrencystringNoOptional source currency filter.
fromNetworkstringNoOptional source network filter.
toCurrencystringNoOptional destination currency filter.
toNetworkstringNoOptional destination network filter.
flow`'standard''fixed-rate'`No

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/pairs?fromCurrency=btc&toCurrency=eth'

Example Response

[
  {
    "fromCurrency": "btc",
    "fromNetwork": "btc",
    "toCurrency": "eth",
    "toNetwork": "eth",
    "flow": {
      "standard": true,
      "fixedRate": true
    }
  }
]

3. Get Min Amount

Returns the minimum supported source amount for a route.

Endpoint

GET /min-amount

Query Parameters

FieldTypeRequiredDescription
fromCurrencystringYesSource asset ticker.
fromNetworkstringNoSource network.
toCurrencystringYesDestination asset ticker.
toNetworkstringNoDestination network.
flow`'standard''fixed-rate'`No

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/min-amount?fromCurrency=btc&fromNetwork=btc&toCurrency=eth&toNetwork=eth'

Example Response

{
  "fromCurrency": "btc",
  "fromNetwork": "btc",
  "toCurrency": "eth",
  "toNetwork": "eth",
  "flow": "standard",
  "minAmount": 0.0002787
}

4. Get Range

Returns the minimum and maximum supported source amount for a route.

Endpoint

GET /range

Query Parameters

Same as GET /min-amount.

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/range?fromCurrency=btc&fromNetwork=btc&toCurrency=eth&toNetwork=eth&flow=standard'

Example Response

{
  "fromCurrency": "btc",
  "fromNetwork": "btc",
  "toCurrency": "eth",
  "toNetwork": "eth",
  "flow": "standard",
  "minAmount": 0.0002625,
  "maxAmount": null
}

5. Get Estimated Amount

Returns a quote estimate for the selected route.

Endpoint

GET /estimated-amount

Query Parameters

FieldTypeRequiredDescription
fromCurrencystringYesSource asset ticker.
fromNetworkstringNoSource network.
toCurrencystringYesDestination asset ticker.
toNetworkstringNoDestination network.
fromAmountstringFor directSource amount.
toAmountstringFor reverseDestination amount.
refundAddressstringNoOptional refund address.
flow`'standard''fixed-rate'`No
type`'direct''reverse'`No
useRateIdstringNoSet to true to request a reusable rateId for fixed-rate quotes.

Direct Fixed-Rate Example

curl --request GET \
  --url 'https://back.2aml.com/external/swap/estimated-amount?fromCurrency=btc&fromNetwork=btc&toCurrency=eth&toNetwork=eth&fromAmount=0.001&flow=fixed-rate&type=direct&useRateId=true'

Reverse Fixed-Rate Example

curl --request GET \
  --url 'https://back.2aml.com/external/swap/estimated-amount?fromCurrency=btc&fromNetwork=btc&toCurrency=eth&toNetwork=eth&toAmount=0.03&flow=fixed-rate&type=reverse&useRateId=true'

Example Response

{
  "fromCurrency": "btc",
  "fromNetwork": "btc",
  "toCurrency": "eth",
  "toNetwork": "eth",
  "flow": "fixed-rate",
  "type": "direct",
  "rateId": "dzmw56abdj0hvodg_4y26aqcy8yfiyyp",
  "validUntil": "2026-05-03T12:45:00.000Z",
  "transactionSpeedForecast": "10-60",
  "warningMessage": null,
  "fromAmount": 0.001,
  "toAmount": 0.03312805,
  "depositFee": 0,
  "withdrawalFee": 0
}

Response Fields

FieldTypeDescription
fromCurrencystringSource asset.
fromNetwork`stringnull`
toCurrencystringDestination asset.
toNetwork`stringnull`
flowstringQuote flow.
typestringRequest mode.
rateId`stringnull`
validUntil`stringnull`
transactionSpeedForecast`stringnull`
warningMessage`stringnull`
fromAmountnumberSource amount for the quote.
toAmountnumberDestination amount for the quote.
depositFeenumberEstimated deposit-side fee.
withdrawalFeenumberEstimated withdrawal-side fee.

6. Get Network Fee

Returns estimated fee data for the selected route.

Endpoint

GET /network-fee

Query Parameters

FieldTypeRequiredDescription
fromCurrencystringYesSource asset ticker.
fromNetworkstringNoSource network.
toCurrencystringYesDestination asset ticker.
toNetworkstringNoDestination network.
fromAmountstringNoSource amount.
toAmountstringNoDestination amount.
refundAddressstringNoOptional refund address.
flow`'standard''fixed-rate'`No
type`'direct''reverse'`No
convertedCurrencystringNoOptional conversion currency for fee display.
convertedNetworkstringNoOptional conversion network.

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/network-fee?fromCurrency=btc&fromNetwork=btc&toCurrency=eth&toNetwork=eth&fromAmount=0.001&flow=fixed-rate&type=direct&convertedCurrency=usd'

Example Response

{
  "estimatedFee": {
    "deposit": {
      "currency": "btc",
      "network": "btc",
      "amount": 0.00013
    },
    "withdrawal": {
      "currency": "eth",
      "network": "eth",
      "amount": 0.0012
    },
    "totals": {
      "from": {
        "currency": "btc",
        "network": "btc",
        "amount": 0.00013
      },
      "to": {
        "currency": "eth",
        "network": "eth",
        "amount": 0.0012
      }
    },
    "converted": {
      "currency": "usd",
      "deposit": 4.21,
      "withdrawal": 3.17,
      "total": 7.38
    }
  }
}

7. Get Market Estimate

Returns a display-oriented market conversion estimate. This endpoint is not an executable order quote.

Endpoint

GET /markets/estimate

Query Parameters

FieldTypeRequiredDescription
fromCurrencystringYesSource asset ticker.
fromNetworkstringNoSource network.
toCurrencystringYesDestination asset ticker.
toNetworkstringNoDestination network.
fromAmountstringFor directSource amount.
toAmountstringFor reverseDestination amount.
type`'direct''reverse'`No

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/markets/estimate?fromCurrency=usdt&fromNetwork=trx&toCurrency=btc&toNetwork=btc&fromAmount=1000&type=direct'

Example Response

{
  "fromCurrency": "usdt",
  "fromNetwork": "trx",
  "toCurrency": "btc",
  "toNetwork": "btc",
  "fromAmount": 1000,
  "toAmount": 0.09527438736782325,
  "type": "direct"
}

8. Validate Address

Validates the destination payout address.

Endpoint

GET /validate/address

Query Parameters

FieldTypeRequiredDescription
currencystringYesDestination asset ticker.
networkstringNoDestination network hint.
addressstringYesDestination address.

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/validate/address?currency=eth&network=eth&address=0x57f31ad4b64095347F87eDB1675566DAfF5EC886'

Example Response

{
  "valid": true,
  "reason": null,
  "addressActive": null
}

9. Create Order

Creates a swap order.

Endpoint

POST /orders

Request Body

FieldTypeRequiredDescription
fromCurrencystringYesSource asset ticker.
fromNetworkstringNoSource network.
fromAmountstringFor directSource amount.
toCurrencystringYesDestination asset ticker.
toNetworkstringNoDestination network.
toAmountstringFor reverseDestination amount.
destinationAddressstringYesDestination payout address.
destinationExtraIdstringNoDestination memo or tag when required.
refundAddressstringNoOptional refund address.
refundExtraIdstringNoOptional refund memo or tag.
rateIdstringNoFixed-rate token obtained from the quote endpoint.
fingerprintstringNoOptional attribution fingerprint.
referralCodestringNoOptional referral code.
acceptedTermsbooleanYesMust be true.
type`'direct''reverse'`No
flow`'standard''fixed-rate'`No

Example Request

curl --request POST \
  --url 'https://back.2aml.com/external/swap/orders' \
  --header 'Content-Type: application/json' \
  --header 'x-fingerprint: fp_8bcafb2f41' \
  --data '{
    "fromCurrency": "btc",
    "fromNetwork": "btc",
    "fromAmount": "0.001",
    "toCurrency": "eth",
    "toNetwork": "eth",
    "destinationAddress": "0x57f31ad4b64095347F87eDB1675566DAfF5EC886",
    "acceptedTerms": true,
    "flow": "fixed-rate",
    "type": "direct",
    "rateId": "dzmw56abdj0hvodg_4y26aqcy8yfiyyp"
  }'

Example Response

{
  "orderId": "ORD-20260503-AB12CD34",
  "status": "awaiting_deposit",
  "message": "Send the exact deposit asset to the provided payment address.",
  "deposit": {
    "currency": "btc",
    "network": "btc",
    "amount": "0.001"
  },
  "receive": {
    "currency": "eth",
    "network": "eth",
    "amount": "0.03312805"
  },
  "payment": {
    "address": "3M7QKsJDKbVZAhFPpFSVtVQv6Nzon3Lwtv",
    "extraId": null,
    "reference": "PAY-ORD-20260503-AB12CD34",
    "qrPayload": "bitcoin:3M7QKsJDKbVZAhFPpFSVtVQv6Nzon3Lwtv?amount=0.001",
    "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "steps": {
    "awaitingDeposit": "waiting",
    "confirming": "waiting",
    "processing": "waiting",
    "sending": "waiting"
  },
  "updatedAt": "2026-05-03T12:30:00.000Z"
}

Response Fields

FieldTypeDescription
orderIdstringCanonical order identifier.
statusstringCurrent order status.
messagestringCustomer-facing status message.
depositobjectSource asset, network, and amount for this order.
receiveobjectDestination asset, network, and amount for this order.
payment`objectnull`
stepsobjectProgress summary.
updatedAtstringLast update timestamp.

payment.reference is a customer-facing reference value. payment.address and the related QR data must be treated as active only while payment is present in the response.

10. Get Order

Returns the latest customer-facing order status by orderId.

Endpoint

GET /orders/:orderId

Example Request

curl --request GET \
  --url 'https://back.2aml.com/external/swap/orders/ORD-20260503-AB12CD34'

Example Response

{
  "orderId": "ORD-20260503-AB12CD34",
  "status": "confirming",
  "message": "Deposit detected. Waiting for blockchain confirmation.",
  "deposit": {
    "currency": "btc",
    "network": "btc",
    "amount": "0.001"
  },
  "receive": {
    "currency": "eth",
    "network": "eth",
    "amount": "0.03312805"
  },
  "payment": {
    "address": "3M7QKsJDKbVZAhFPpFSVtVQv6Nzon3Lwtv",
    "extraId": null,
    "reference": "PAY-ORD-20260503-AB12CD34",
    "qrPayload": "bitcoin:3M7QKsJDKbVZAhFPpFSVtVQv6Nzon3Lwtv?amount=0.001",
    "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "steps": {
    "awaitingDeposit": "done",
    "confirming": "waiting",
    "processing": "waiting",
    "sending": "waiting"
  },
  "updatedAt": "2026-05-03T12:32:00.000Z"
}

Polling Recommendation

  • awaiting_deposit: poll every 10 to 20 seconds
  • confirming: poll every 10 seconds
  • processing: poll every 10 seconds
  • sending: poll every 10 seconds
  • terminal states: stop polling

Error Responses

All errors in this namespace use the following structure:

{
  "statusCode": 400,
  "timestamp": "2026-05-03T12:40:00.000Z",
  "path": "/external/swap/orders",
  "error": {
    "message": "Order request is invalid."
  }
}

Validation Error Example

{
  "statusCode": 400,
  "timestamp": "2026-05-03T12:40:00.000Z",
  "path": "/external/swap/orders",
  "error": {
    "message": [
      "fromCurrency should not be empty",
      "toCurrency should not be empty",
      "acceptedTerms must be a boolean value"
    ]
  }
}

Not Found Example

{
  "statusCode": 404,
  "timestamp": "2026-05-03T12:40:00.000Z",
  "path": "/external/swap/orders/ORD-DOES-NOT-EXIST",
  "error": {
    "message": "Order not found."
  }
}

Rate Limit Example

{
  "statusCode": 429,
  "timestamp": "2026-05-03T12:40:00.000Z",
  "path": "/external/swap/orders",
  "error": {
    "message": "Too many requests. Please try again shortly."
  }
}

Temporary Service Error Example

{
  "statusCode": 503,
  "timestamp": "2026-05-03T12:40:00.000Z",
  "path": "/external/swap/estimated-amount",
  "error": {
    "message": "Swap service is temporarily unavailable."
  }
}

Reference Schemas

type SwapCurrency = {
  currency: string;
  network: string;
  name: string;
  supportsFixedRate: boolean;
  destinationExtraIdSupported: boolean;
  destinationExtraIdRequired: boolean;
  isStable: boolean;
  isFiat: boolean;
  tokenContract: string | null;
};

type SwapPair = {
  fromCurrency: string;
  fromNetwork: string;
  toCurrency: string;
  toNetwork: string;
  flow: {
    standard: boolean;
    fixedRate: boolean;
  };
};

type SwapEstimate = {
  fromCurrency: string;
  fromNetwork: string | null;
  toCurrency: string;
  toNetwork: string | null;
  flow: string;
  type: string;
  rateId: string | null;
  validUntil: string | null;
  transactionSpeedForecast: string | null;
  warningMessage: string | null;
  fromAmount: number;
  toAmount: number;
  depositFee: number;
  withdrawalFee: number;
};

type SwapOrder = {
  orderId: string;
  status:
    | 'awaiting_deposit'
    | 'confirming'
    | 'processing'
    | 'sending'
    | 'completed'
    | 'failed'
    | 'refunded'
    | 'pending_support';
  message: string;
  deposit: {
    currency: string | null;
    network: string | null;
    amount: string | null;
  };
  receive: {
    currency: string | null;
    network: string | null;
    amount: string | null;
  };
  payment: {
    address: string;
    extraId: string | null;
    reference: string;
    qrPayload: string | null;
    qrCodeDataUrl: string | null;
  } | null;
  steps: {
    awaitingDeposit: 'waiting' | 'done';
    confirming: 'waiting' | 'done';
    processing: 'waiting' | 'done';
    sending: 'waiting' | 'done';
  };
  updatedAt: string;
};

Private Send API

Public API reference for private-send quotes, order creation, and order tracking.

Rent TRON Energy API

Public API reference for customer authentication, wallet top-up, quotes, and TRON energy order management.

On this page

Swap APIBase URLAuthenticationGeneral ConventionsIntegration FlowRequest ModesDirect RequestsReverse RequestsFixed-Rate QuotesRefund AddressOrder StatusEndpoint Summary1. List CurrenciesEndpointQuery ParametersExample RequestExample ResponseResponse Fields2. List PairsEndpointQuery ParametersExample RequestExample Response3. Get Min AmountEndpointQuery ParametersExample RequestExample Response4. Get RangeEndpointQuery ParametersExample RequestExample Response5. Get Estimated AmountEndpointQuery ParametersDirect Fixed-Rate ExampleReverse Fixed-Rate ExampleExample ResponseResponse Fields6. Get Network FeeEndpointQuery ParametersExample RequestExample Response7. Get Market EstimateEndpointQuery ParametersExample RequestExample Response8. Validate AddressEndpointQuery ParametersExample RequestExample Response9. Create OrderEndpointRequest BodyExample RequestExample ResponseResponse Fields10. Get OrderEndpointExample RequestExample ResponsePolling RecommendationError ResponsesValidation Error ExampleNot Found ExampleRate Limit ExampleTemporary Service Error ExampleReference Schemas
2AML2AML

2AML is a technology and integration platform for digital asset workflows, built to provide clear service flows, transaction visibility, and support tools.

XTelegram botWhatsApp botDCin

Products

Company

Support

Legal

© 2026 2AML. All rights reserved. Use of this platform is subject to our Terms of Service.

Trustpilot