HMAC

When should I use HMAC authentication?

Use HMAC authentication when you are planning to integrate with:

• Paxful Kiosk
• Paxful Pay

HMAC authentication can also be used to authenticate to Paxful API. Since 2022 HMAC authentication for Paxful API is deprecated, it will be maintained for a little while, but no new features will be added. If you are developing a new application, you should use direct or delegated access modes instead.

How do I use HMAC authentication?

HMAC authentication is a process of taking all parameters you want to invoke an endpoint with, “signing” them using your API secret, and then adding the value of this signature as another parameter to the payload of request. When Paxful’s server receives a request with HMAC signature, it will repeat this process. If the signature provided in request payload matches the signature recreated on the authentication server, the request will be processed. If there is a mismatch between signatures, the request has been tampered with and it will be discarded.

Prerequisites

• HMAC API key created on Marketplace

Steps

Follow these steps to create a request signed with HMAC signature:

1. Take parameters with values (along with an API key itself, its parameter should be called “apikey”) that you would like to send to an endpoint and urlencode them.
2. Pass urlencoded parameters to HMAC SHA256 encoding function.
3. Append output of HMAC SHA256 function as a last parameter to the urlencoded string from step 1). The parameter should be called “apiseal".

After following these steps you should have a signed payload which, depending on the use-case, you can use in a few different ways:

• If you are integrating with Paxful Kiosk or Paxful Pay, you need to use the signed payload as a query string. For more information, see the Paxful Kiosk or Paxful Pay integration guides.
• If you are planning to use HMAC to authenticate Paxful API, you can use the signed payload as a body of a POST request. For more information, see the Paxful API section below.

HMAC signature generation functions

JavaScript (NodeJs)
const qs = require('querystring');
const crypto = require('crypto');

function sign_with_hmac(apiKey, apiSecret, payload = {}) {
    payload = qs.encode({
        apikey: apiKey,
        nonce: Date.now(),
        ...payload
    });

    const apiSeal = crypto.createHmac('sha256', apiSecret).update(payload).digest('hex');
    const signedPayload = `${payload}&apiseal=${apiSeal}`;

    return signedPayload;
}

PHP
function sign_with_hmac($apiKey, $apiSecret, array $payload = []) {
    $payload = array_merge($payload, [
        'apikey' => $apiKey,
        'nonce' => time()
    ]);

    $apiSeal = hash_hmac('sha256', http_build_query($payload), $apiSecret);
    $signedPayload = http_build_query(array_merge($payload, ['apiseal' => $apiSeal]));

    return $signedPayload;
}

Python 3
import hmac
import time
from hashlib import sha256
from urllib.parse import urlencode


def sign_with_hmac(api_key, api_secret, **kwargs):
    nonce = int(time.time())

    payload = {"apikey": api_key, "nonce": nonce}
    payload.update(kwargs)

    payload = urlencode(sorted(payload.items()))
    apiseal = hmac.new(api_secret.encode(), payload.encode(), sha256).hexdigest()

    return payload + "&apiseal=" + apiseal

Golang
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"net/url"
	"strings"
	"time"
)

func SignWithHmac(paxfulAPIKey string, paxfulSecretAPIKey string, values url.Values) string {
	nonce := fmt.Sprintf("%d", time.Now().Unix())

	values.Add("apikey", paxfulAPIKey)
	values.Add("nonce", nonce)

	payload := values.Encode()

	mac := hmac.New(sha256.New, []byte(paxfulSecretAPIKey))
	mac.Write([]byte(payload))
	apiseal := hex.EncodeToString(mac.Sum(nil))

	values.Add("apiseal", apiseal)

	return values.Encode()
}