Build Your Signer Endpoint

The signer is a server-side HTTP endpoint that receives a SignerRequest from the Deposit SDK, creates a signed payment link, and returns a SignerResponse. This is the core security mechanism. It ensures every payment was authorized by your server.

Request format

The Deposit SDK sends a POST request with this JSON body to your signer URL:

Field	Type	Description
`amount`	`number`	USD amount to deposit. Always > 0.
`chainId`	`number?`	Destination chain ID (for example, `8453` for Base, `42161` for Arbitrum, or `792703809` for Solana). Present for a single-destination request; absent when `destinations` is sent.
`address`	`string?`	Destination wallet address. In the web SDK this can be an EVM address or a Solana address, depending on the destination chain. Present with `chainId`.
`token`	`string?`	Destination token identifier for that chain. Use an EVM token contract address on EVM chains or an SPL mint address on Solana. Present with `chainId`.
`destinations`	`Array<{ chainId, address, token }>?`	The destination menu, most-preferred first, when the app requested a deposit with several accepted (chain, token, address) pairs. Present instead of `chainId`/`address`/`token`, never alongside them. 1–10 entries. See Multiple destinations.
`callbackScheme`	`string \| null`	Always `null` for browser integrations. Reserved for native app deep-link callbacks.
`url`	`string`	Base webview URL the SDK will navigate to. Provided for logging/validation only. Your signer does not construct the final URL.
`version`	`string`	Protocol version (currently `"v1"`).
`reference`	`string?`	Optional merchant order or invoice ID for reconciliation.
`metadata`	`Record<string, string>?`	Optional arbitrary key-value pairs for your records.

Example request body:

{
  "amount": 50,
  "chainId": 8453,
  "address": "0x1a5FdBc891c5D4E6aD68064Ae45D43146D4F9f3a",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "callbackScheme": null,
  "url": "https://pay.blink.cash",
  "version": "v1",
  "reference": "order-123",
  "metadata": { "invoiceId": "INV-456" }
}

Implementation steps

Your endpoint must perform these steps in order:

1. Validate the request

Field	Validation Rule
`amount`	`Number.isFinite(amount) && amount > 0`
`chainId`	`Number.isInteger(chainId) && chainId > 0`
`address`	Validate based on the requested destination chain. For the web SDK, accept EVM addresses on EVM chains and Solana Base58 addresses on Solana.
`token`	Validate based on the requested destination chain. For the web SDK, accept EVM contract addresses on EVM chains and SPL mint addresses on Solana.
`callbackScheme`	`null` or matches `/^[a-zA-Z][a-zA-Z0-9+\-.]*$/`
`version`	Non-empty string (default to `"v1"` if missing)

Return HTTP 400 with an error message for any validation failure.

Your signer should allowlist only Blink-supported destination chainId and token combinations. See Supported Networks and Wallets for the current routing catalog.

2. Verify destination ownership

Before signing, confirm that the authenticated user actually controls the destination address. Without this check, a malicious caller could submit someone else’s wallet address and direct funds to an account they don’t own.

When the request carries destinations, run this check over every entry in the array, not just the first. A signer that verifies one address and signs three has authorized deposits to two addresses it never checked.

Your signer should look up the user’s wallets via your auth provider and verify the requested address is among them. Here is an example using Privy as the auth provider:

const { PrivyClient } = require('@privy-io/server-auth');

const privy = new PrivyClient(process.env.PRIVY_APP_ID, process.env.PRIVY_APP_SECRET);

async function verifyDestinationOwnership(authToken, requestedAddress) {
  const { userId } = await privy.verifyAuthToken(authToken);
  const user = await privy.getUser(userId);

  const userWallets = user.linkedAccounts
    .filter((a) => a.type === 'wallet')
    .map((a) => a.address.toLowerCase());

  if (!userWallets.includes(requestedAddress.toLowerCase())) {
    return false;
  }
  return true;
}

In your route handler, call this before proceeding to signing:

const authToken = req.headers.authorization?.replace('Bearer ', '');
const ownsAddress = await verifyDestinationOwnership(authToken, req.body.address);
if (!ownsAddress) {
  return res.status(403).json({ error: 'Destination address does not belong to the authenticated user.' });
}

If you use a different auth provider, the principle is the same: resolve the caller’s identity, fetch their linked wallets, and reject the request if the destination address is not among them.

3. Generate an idempotency key

Generate a UUID v4 for this payment request. This prevents duplicate transfers if the user retries.

const { randomUUID } = require('node:crypto');
const idempotencyKey = randomUUID();

4. Record the signature timestamp

Record the current time as the signature timestamp. Swype enforces a maximum signature age of 15 minutes server-side, so you do not need to manage expiration TTLs yourself.

const signatureTimestamp = new Date().toISOString();

5. Build the payload JSON

Copy the destination shape you received: the singular triple for a single-destination request, or destinations for a menu. Never sign both.

const payloadObject = {
  amount: request.amount,
  ...(request.destinations
    ? { destinations: request.destinations }
    : { chainId: request.chainId, address: request.address, token: request.token }),
  idempotencyKey,
  callbackScheme: request.callbackScheme,
  signatureTimestamp,
  version: request.version,
};

6. Base64url-encode the payload

Convert the JSON string to a base64url-encoded string. Base64url uses - instead of +, _ instead of /, and no padding.

const payload = Buffer.from(JSON.stringify(payloadObject), 'utf8').toString('base64url');

6. Sign the payload

Sign the encoded payload string (not the raw JSON) using ECDSA P-256 with SHA-256, then base64url-encode the signature:

const { createSign } = require('node:crypto');

const signer = createSign('SHA256');
signer.update(payload);
signer.end();
const signature = signer.sign(privateKeyPem).toString('base64url');

The input to the signing function is the base64url-encoded payload string (ASCII bytes). The output is the raw DER-encoded ECDSA signature, which is then base64url-encoded.

8. Return the response

Response format

Field	Type	Description
`merchantId`	`string`	Your merchant UUID (from Blink registration).
`payload`	`string`	Base64url-encoded payment payload.
`signature`	`string`	Base64url-encoded ECDSA signature of the payload string.
`preview`	`object`	Echo of payment parameters for client-side display.
`preview.amount`	`number`	Deposit amount.
`preview.chainId`	`number`	Destination chain ID (the first entry, for a menu).
`preview.address`	`string`	Destination wallet address.
`preview.token`	`string`	Destination token contract address.
`preview.destinations`	`array?`	Echo of the signed menu, when one was requested.
`preview.idempotencyKey`	`string`	The generated idempotency key.

Example response:

{
  "merchantId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "payload": "eyJhbW91bnQiOjUwLCJjaGFpbklkIjo4NDUz...",
  "signature": "MEUCIQC3k9F...",
  "preview": {
    "amount": 50,
    "chainId": 8453,
    "address": "0x1a5FdBc891c5D4E6aD68064Ae45D43146D4F9f3a",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

Multiple destinations

A user is usually credited at one place: one chain, one token, one wallet address. Some apps can credit the same user at several — USDT on Tron, USDT on Ethereum and USDC on Polygon, say, each at its own address. Pass those as destinations on the deposit request and sign them through as a menu:

{
  "amount": 50,
  "destinations": [
    { "chainId": 728126428, "address": "TQn9Y2…", "token": "TR7NHq…" },
    { "chainId": 1,         "address": "0x1a5F…", "token": "0xdAC1…" },
    { "chainId": 137,       "address": "0x9bC1…", "token": "0x3c49…" }
  ],
  "idempotencyKey": "f47ac10b-…",
  "callbackScheme": null,
  "signatureTimestamp": "2026-09-01T12:00:00.000Z",
  "version": "v1"
}

What Blink does with a menu. Every deposit settles on exactly one entry, chosen from the asset the user sends:

A source that matches an entry’s chain and token settles there directly — no bridge, no swap, no fee.
Otherwise the same asset on another chain is preferred, then a different token on the same chain, then anything else.
An Ethereum entry is chosen last unless it is a direct match, because destination gas comes out of the delivered amount.
Ties break on your order, so list the destinations you would rather receive first.

Tron entries are honoured on the manual (send-to-address) rail only; Blink one-tap never settles on Tron. Rules. 1–10 entries. No two entries may share a chain and token. Each address must have the shape of its chain (0x hex on EVM, Base58 on Solana and Tron). Send destinations instead of chainId/address/token — a payload carrying both, where the triple is not one of the entries, is rejected. Your signer’s job does not change, except that the ownership check in step 2 must cover every address in the array.

Complete Node.js implementation

A copy-paste-ready Express.js signer endpoint. Replace YOUR_MERCHANT_ID and load your private key from a secure source.

const express = require('express');
const { randomUUID, createSign } = require('node:crypto');
const fs = require('node:fs');

const app = express();
app.use(express.json());

const MERCHANT_ID = process.env.MERCHANT_ID || 'YOUR_MERCHANT_ID';
const PRIVATE_KEY_PEM = process.env.MERCHANT_PRIVATE_KEY
  || fs.readFileSync('./private.pem', 'utf8');

function encodeBase64Url(value) {
  return Buffer.from(value, 'utf8').toString('base64url');
}

function signPayload(payload, privateKeyPem) {
  const signer = createSign('SHA256');
  signer.update(payload);
  signer.end();
  return signer.sign(privateKeyPem).toString('base64url');
}

function validateDestination({ chainId, address, token }, errors, label = '') {
  if (!Number.isInteger(chainId) || chainId <= 0) {
    errors.push(`chainId must be a positive integer${label}.`);
  }
  if (typeof address !== 'string' || !/^0x[a-fA-F0-9]{40}$/.test(address)) {
    errors.push(`address must be a 0x-prefixed, 40-character hex string${label}.`);
  }
  if (typeof token !== 'string' || !/^0x[a-fA-F0-9]{1,40}$/.test(token)) {
    errors.push(`token must be a 0x-prefixed hex contract address${label}.`);
  }
}

function validateRequest(body) {
  const errors = [];
  const { amount, destinations, callbackScheme } = body;

  if (!Number.isFinite(amount) || amount <= 0) {
    errors.push('amount must be a positive number.');
  }
  if (destinations !== undefined) {
    // Menu shape: 1–10 entries, each validated, no chain+token listed twice.
    if (!Array.isArray(destinations) || destinations.length === 0 || destinations.length > 10) {
      errors.push('destinations must list 1 to 10 entries.');
    } else {
      destinations.forEach((d, i) => validateDestination(d, errors, ` (destinations[${i}])`));
    }
  } else {
    validateDestination(body, errors);
  }
  if (
    callbackScheme !== null &&
    callbackScheme !== undefined &&
    (typeof callbackScheme !== 'string' ||
      !/^[a-zA-Z][a-zA-Z0-9+\-.]*$/.test(callbackScheme))
  ) {
    errors.push('callbackScheme must be null or a valid URI scheme.');
  }

  return errors;
}

app.post('/api/sign-payment', (req, res) => {
  const errors = validateRequest(req.body);
  if (errors.length > 0) {
    return res.status(400).json({ error: errors.join(' ') });
  }

  const { amount, chainId, address, token, destinations, callbackScheme = null, version = 'v1' } = req.body;

  // Verify the caller owns EVERY address you are about to sign for.
  const addressesToVerify = destinations ? destinations.map((d) => d.address) : [address];
  // ... your ownership check over addressesToVerify goes here ...

  const idempotencyKey = randomUUID();
  const signatureTimestamp = new Date().toISOString();

  const payloadObject = {
    amount,
    ...(destinations ? { destinations } : { chainId, address, token }),
    idempotencyKey, callbackScheme, signatureTimestamp, version,
  };

  const payload = encodeBase64Url(JSON.stringify(payloadObject));
  const signature = signPayload(payload, PRIVATE_KEY_PEM);

  res.setHeader('Cache-Control', 'no-store');
  res.json({
    merchantId: MERCHANT_ID,
    payload,
    signature,
    preview: destinations
      ? { amount, ...destinations[0], destinations, idempotencyKey }
      : { amount, chainId, address, token, idempotencyKey },
  });
});

const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
  console.log(`Merchant signer listening on port ${PORT}`);
});

Python implementation

For merchants using Python:

import json
import uuid
import base64
from datetime import datetime, timezone
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec

def base64url_encode(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')

def sign_payment(
    private_key_pem: str,
    merchant_id: str,
    amount: float,
    chain_id: int,
    address: str,
    token: str,
    callback_scheme: str | None = None,
    version: str = "v1",
) -> dict:
    idempotency_key = str(uuid.uuid4())
    signature_timestamp = datetime.now(timezone.utc).isoformat()

    payload_obj = {
        "amount": amount,
        "chainId": chain_id,
        "address": address,
        "token": token,
        "idempotencyKey": idempotency_key,
        "callbackScheme": callback_scheme,
        "signatureTimestamp": signature_timestamp,
        "version": version,
    }

    payload = base64url_encode(json.dumps(payload_obj).encode("utf-8"))

    private_key = serialization.load_pem_private_key(private_key_pem.encode(), password=None)
    signature_bytes = private_key.sign(
        payload.encode("utf-8"),
        ec.ECDSA(hashes.SHA256()),
    )
    signature = base64url_encode(signature_bytes)

    return {
        "merchantId": merchant_id,
        "payload": payload,
        "signature": signature,
        "preview": {
            "amount": amount,
            "chainId": chain_id,
            "address": address,
            "token": token,
            "idempotencyKey": idempotency_key,
        },
    }

Signing algorithm summary

For merchants implementing the signer in any language:

Build the payload as a JSON string with fields: amount, chainId, address, token, idempotencyKey, callbackScheme, signatureTimestamp, version.
Base64url-encode the JSON string (UTF-8 bytes to base64url, no padding).
Sign the base64url-encoded string (not the raw JSON) using ECDSA with P-256 (prime256v1/secp256r1) and SHA-256. The input to the sign function is the ASCII bytes of the base64url string.
Base64url-encode the raw signature bytes (DER format).
Return the encoded payload, encoded signature, your merchant ID, and a preview object.

Security requirements

The signer endpoint is a security-critical component. A compromised signer allows unauthorized payment link creation.

HTTPS only. Never serve the signer over plain HTTP in production.
Authenticate callers. The signer should only accept requests from your own frontend. Use session cookies, auth tokens, or CORS restrictions.
Verify destination ownership. Confirm the authenticated user controls the destination address before signing. Without this, a malicious user could redirect funds to a wallet they don’t own. See step 2 above.
Server-enforced expiry. Swype enforces a maximum signature age of 15 minutes. Include signatureTimestamp in every payload so Swype can reject stale signatures. You do not need to manage expiration TTLs yourself.
Rate limit. Protect against abuse by rate-limiting signer requests per user/session.
Log, but never log the private key. Log request metadata for debugging, but never log the private key or raw signature in production.
CORS. Configure CORS to only allow your frontend origin(s).

​Request format

​Implementation steps

​1. Validate the request

​2. Verify destination ownership

​3. Generate an idempotency key

​4. Record the signature timestamp

​5. Build the payload JSON

​6. Base64url-encode the payload

​6. Sign the payload

​8. Return the response

​Response format

​Multiple destinations

​Complete Node.js implementation

​Python implementation

​Signing algorithm summary

​Security requirements

Request format

Implementation steps

1. Validate the request

2. Verify destination ownership

3. Generate an idempotency key

4. Record the signature timestamp

5. Build the payload JSON

6. Base64url-encode the payload

6. Sign the payload

8. Return the response

Response format

Multiple destinations

Complete Node.js implementation

Python implementation

Signing algorithm summary

Security requirements