📘Get Transactions

This endpoint allows for mass querying of all transactions created by your users.

Type: POST

URL: https://widget.swapped.com/api/v1/merchant/get_transactions

Params:

• apiKey: Required, your public key.

• timestamp: Required, an ISO 8601 formatted UTC timestamp within 5 seconds of the request being received.

• signature: Required, SHA-256 hash of the body using your secret key. See below for more information on how to generate this.

• page: Optional, the page number you wish to access.

• limit: Optional, the number of results per page, max: 100.

• start_date: Optional, ISO 8601 formatted UTC timestamp.

• end_date: Optional, ISO 8601 formatted UTC timestamp.

• order_id: Optional, the Swapped.com order ID

Example Body:

{
    "apiKey": "public_key",
    "timestamp": "2025-05-16T09:38:25.000Z",
    "signature": "RAsRZUtDHhyY/On0qWZcxVdQ0AAQE+yUWk1/sf/pnI0="
}

Example Response:

{
    "success": true,
    "data": {
        "orders": [
            {
                "order_id": "61b1d8f0-ab0e-4e18-b541-c62489d3869c",
                "created_at": "2025-11-10 00:32:20.812857+00",
                "updated_at": "2025-11-10 00:32:20.967135",
                "user_id": "8e93ccf4-5b44-4ce0-82d4-e64e0399a653",
                "order_total": 1529.27,
                "order_crypto": "XRP",
                "order_currency": "DKK",
                "order_status": "payment_pending",
                "order_payment_method": "bank-transfer",
                "order_type": "buy",
                "order_crypto_amount": 96.881233778549,
                "processing_fee": 7.65,
                "network_fee": 0,
                "fiat_rate": "7.467126",
                "blockchain_address": "raV5bXp9hNe5G4YFxLDSGHExL3bVyYmwZ9",
                "order_crypto_price": 2.06379,
                "transaction_id": null,
                "order_total_eur": 204.80034755005,
                "external_transaction_id": null,
                "external_customer_id": null,
                "merchant": "Test",
                "handling_fee": 3.932167,
                "response_url": "https://webhook.site/Swapped",
                "merchant_poi": false,
                "merchant_poa": false,
                "merchant_vip": false,
                "destination_tag": null,
                "crypto_network": "xrp",
                "markup": "0",
                "markup_total_eur": "0",
                "payment_group": "bank-transfer",
                "user_country": "BE"
            }
        ],
        "total": 1,
        "page": 1,
        "limit": 1,
        "pages": 1
    }
}

The get_transactions endpoint only returns the following states:

• order_completed

• order_cancelled

• payment_pending

order_broadcasted is a pseudo-state used only for merchant callbacks.

To infer if an order has been broadcast to the blockchain (i.e. order_broadcasted):

• If order.transaction_id is set = it's been broadcast.

• If order.transaction_id is null = it's still pending broadcast.

All values for the following keys will always be in EUR:

• processing_fee

• network_fee

• order_crypto_price

• order_total_eur

• handling_fee

order_total will always be in the currency denoted in order_currency

Order JSON Structure

The JSON response detailed above provides comprehensive information about a user's order. Below is a breakdown of key fields present within each order object:

Order Details

• User Information:

  • user_id: Unique identifier for a swapped.com user.

  • user_country: The user's country.

  • merchant_vip: Is the user a VIP with the merchant

  • merchant_poa: Has the user completed proof of address with the merchant.

  • merchant_poi: Has the user completed proof of identity with the merchant.

• Cryptocurrency Details:

  • order_crypto: Cryptocurrency type (e.g., BTC).

  • order_crypto_amount: Amount of cryptocurrency in the transaction. Note this is updated when crypto is sent out.

  • order_crypto_price: Price of the cryptocurrency at the time of the order. Note this is updated when crypto is sent out.

• Order Information:

  • order_id: Unique identifier for the order.

  • order_type: Type of the order ('buy' or 'sell').

  • order_status: Current status (e.g., payment_pending).

  • order_currency: Fiat currency used (e.g., DKK).

  • order_total: Total order value in the fiat currency.

  • order_total_eur: Total order value in EUR.

  • created_at: Order creation timestamp.

  • updated_at: Timestamp of the last update.

  • order_payment_method: The payment method used.

  • payment_group: The payment group the method belongsto.

• Financial Details:

  • network_fee: Network fee in EUR.

  • fiat_rate: Exposes the exchange rate used when the order was created, showing how local currency was converted to EUR.

  • processing_fee: Processing fee cost for this method in EUR.

  • handling_fee: Swapped's spread (1.92%) + any static processing fees

  • markup: The merchant’s markup fee, if set, is a percentage expressed as a whole number (e.g. 1 = 1%), configurable in the Swapped dashboard.

• Transaction Details:

  • external_customer_id: External identifier for the customer.

  • external_transaction_id: External transaction identifier.

  • transaction_id: Unique blockchain transaction ID.

  • blockchain_address: Cryptocurrency blockchain address.

• Additional Information:

  • network_destination_tag: Destination tag/memo/tag provided for the wallet_address

  • response_url: URL provided for the callback, if provided.

Generating A Signature:

To create a signature, hash the JSON body of the request using your secret key with the SHA-256 algorithm. Make sure the JSON body is in a consistent string format before hashing.

Below are examples of how a signature hash can be generated correctly.

<?php

$data = [
    "apiKey" => "example_public_key",
    "timestamp" => "2025-05-16T09:38:25.000Z"
];

// Convert to JSON string
$json_data = json_encode($data);

echo "Data being signed: <br><pre>" . $json_data . PHP_EOL . "</pre><br>";

// Use the correct secret key, replace with your actual secret key
$secret_key = "example_secret_key";

// Generate signature
$signature = base64_encode(hash_hmac('sha256', $json_data, $secret_key, TRUE));

echo "<br>Generated signature: <br>" . PHP_EOL . $signature . PHP_EOL . "<br>";

// Add signature to the original data array (not the JSON string)
$data['signature'] = $signature;

echo "<br>Data with signature: <br><pre>" . PHP_EOL . json_encode($data) . "</pre>" . PHP_EOL;

Postman Pre-Request Script:

const publicKey = "YOUR KEY HERE";
const secretKey = "YOUR SECRET HERE";

function getISOTimestamp() {
   const now = new Date();
   const pad = (n) => String(n).padStart(2, '0');
   return `${now.getUTCFullYear()}-${pad(now.getUTCMonth()+1)}-${pad(now.getUTCDate())}T${pad(now.getUTCHours())}:${pad(now.getUTCMinutes())}:${pad(now.getUTCSeconds())}+00:00`;
}

const timestamp = getISOTimestamp();

// Get the request body and parse it
const requestBody = JSON.parse(pm.request.body.raw);

// Add/update required fields
requestBody.apiKey = publicKey;
requestBody.timestamp = timestamp;

// Remove signature field if it exists (before signing)
delete requestBody.signature;

// Generate signature from the body
const jsonData = JSON.stringify(requestBody);
const signature = CryptoJS.enc.Base64.stringify(
   CryptoJS.HmacSHA256(jsonData, secretKey)
);

// Add signature back to the body
requestBody.signature = signature;

// Update the request body
pm.request.body.raw = JSON.stringify(requestBody);

// Set environment variables for reference
pm.environment.set("apiKey", publicKey);
pm.environment.set("timestamp", timestamp);
pm.environment.set("signature", signature);

Example postman body (used with the above):

{
  "apiKey": "{{apiKey}}",
  "timestamp": "{{timestamp}}",
  "order_id": "your_order_id_here",
  "signature": "{{signature}}"
}

All /merchant/ endpoints are subject to a global rate limit of 100 requests per second. Exceeding this limit may result in throttling.