> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: "Signatures"
description: "Create and validate request signatures to secure Market API communication"
icon: shield-check
---

# Signatures

Signatures verify the authenticity and integrity of Market API requests by
hashing sorted request parameters together with your secret key. Use the same
algorithm for outgoing API requests and incoming webhook events.

## Algorithm

<Steps>
  <Step title="Start with request fields" icon="braces">
    Use every field except `signature`.
  </Step>

  <Step title="Sort keys alphabetically" icon="arrow-down-a-z">
    Build a deterministic order before concatenating values.
  </Step>

  <Step title="Concatenate key-value pairs" icon="combine">
    Join each key followed by its value without separators.
  </Step>

  <Step title="Append secret key" icon="key-round">
    Add your Market API secret key to the end of the string.
  </Step>

  <Step title="Hash with SHA-256" icon="fingerprint">
    Hex-encode the SHA-256 digest and send it as `signature`.
  </Step>
</Steps>

<Note>
  `amount` is signed without trailing zeros: `2.00` becomes `2`, `2.50`
  becomes `2.5`, `0.90` becomes `0.9`. Webhook bodies carry `amount` with two
  decimal places (`1.00`), so normalize it before validating the signature.
</Note>

## Signature Creation and Validation

<Tabs items={["Python", "JavaScript", "PHP (install)", "PHP"]}>
  <Tab title="Python">
    ```python
    #!/usr/bin/python3
    from decimal import Decimal
    from hashlib import sha256


    def market_api_sig_value(key, value):
        if key == "amount" and isinstance(value, float) and value.is_integer():
            return str(int(value))
        return str(value)


    def market_api_generate_signature(j, secret):
        str_to_hash = ("".join([i + market_api_sig_value(i, j[i]) for i in sorted(j)]) + secret).encode()
        # print(str_to_hash)
        hashed = sha256(str_to_hash).hexdigest()
        return hashed


    def market_api_validate_signature(j, secret):
        nl_sig = j["signature"]
        del j["signature"]
        our_sig = market_api_generate_signature(j, secret)
        return nl_sig == our_sig


    # Validation

    event_data = {
        "amount": 0.9,
        "username": "A49",
        "unique_id": 89968,
        "item_id": "E3yugw",
        "signature": "dc20a4d73447ac51689d6e03115aa135a8d734e610352dda818e830e70a60560"
    }
    assert (market_api_validate_signature(event_data, "key") == True)

    # Generation

    request_data = {
        "user_id": 1,
        "id": 1337,
        "username": "a49",
        "amount": 2.00,
    }
    request_data.update(signature=market_api_generate_signature(request_data, "key"))
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript
    "use strict";
    let crypto = require("crypto");

    const sort_obj = function(obj) {
      return Object.keys(obj).sort().reduce(function (result, key) {
        result[key] = obj[key];
        return result;
      }, {});
    }

    const obj_to_string = function (obj) {
      obj = sort_obj(obj);
      let str = '';
      for (let p in obj) {
          if (obj.hasOwnProperty(p)) {
              str += p + obj[p];
          }
      }
      return str;
    }

    const market_api_generate_signature = function(j, secret){
        const str_to_hash = obj_to_string(j) + secret
        const hashed = crypto.createHash('sha256').update(str_to_hash).digest('hex');
        return hashed
    }
    const market_api_validate_signature = function(j, secret){
      const nl_sig = j["signature"]
      delete j["signature"]
      const our_sig = market_api_generate_signature(j, secret)
      return nl_sig === our_sig
    }

    // Validation

    let data = {
      "amount": 0.9,
      "username": "A49",
      "unique_id": 89968,
      "item_id": "E3yugw",
      "signature": "dc20a4d73447ac51689d6e03115aa135a8d734e610352dda818e830e70a60560"
    }
    let sign_valid = market_api_validate_signature(data, "key")
    console.log(sign_valid)
    ```
  </Tab>

  <Tab title="PHP (install)">
    ```bash
    composer require rainedot/php-nl-market
    ```
  </Tab>

  <Tab title="PHP">
    ```php
    require("vendor/autoload.php");
    $api = new \Rainedot\PhpNlMarket\MarketAPI('YOUR_API_KEY', 1);
    $api->validateRequest($request); // Returns true if request is valid
    ```
  </Tab>
</Tabs>

## Payload Modes

<Tabs>
  <Tab title="Outgoing Request" icon="send">
    Generate `signature` after adding method fields such as `user_id`, `id`,
    `username`, `code`, `amount`, `product`, or `cnt`.

    ```json
    {
      "user_id": 1,
      "id": "grant-001",
      "username": "target_user",
      "code": "E3yugw",
      "signature": "..."
    }
    ```
  </Tab>

  <Tab title="Incoming Webhook" icon="webhook">
    Validate the received `signature` before processing the event.

    ```json
    {
      "kind": "purchase",
      "amount": 0.9,
      "username": "A49",
      "unique_id": 89968,
      "item_id": "E3yugw",
      "signature": "..."
    }
    ```
  </Tab>
</Tabs>

## Checklist

<AccordionGroup>
  <Accordion title="Do not include signature in the signed string" icon="circle-slash" defaultOpen>
    Remove `signature` before generating the comparison hash.
  </Accordion>

  <Accordion title="Preserve values before signing" icon="braces">
    Build the signature from the exact values you send or receive.
  </Accordion>

  <Accordion title="Use the Market API secret" icon="key-round">
    The secret comes from the market API settings page.
  </Accordion>
</AccordionGroup>
