📘Get Transactions

Need help with your integration? Click here to chat with our custom GPT for instant answers.

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.