Developer Documentation

npm init -y
npm install express

export SHA3_API_BASE_URL=https://api.sha3.net
export SHA3_FRONTEND_BASE_URL=https://www.sha3.net
export SHA3_API_KEY=your-api-key
export SHA3_IPN_SECRET=your-ipn-secret
export PUBLIC_BASE_URL=https://merchant.example.com

node server.mjs

import crypto from 'node:crypto';
import express from 'express';

const API_BASE_URL = process.env.SHA3_API_BASE_URL || 'https://api.sha3.net';
const FRONTEND_BASE_URL = process.env.SHA3_FRONTEND_BASE_URL || 'https://www.sha3.net';
const PUBLIC_BASE_URL = required('PUBLIC_BASE_URL');
const API_KEY = required('SHA3_API_KEY');
const IPN_SECRET = required('SHA3_IPN_SECRET');
const PORT = Number(process.env.PORT || 3000);

const app = express();
const seenNonces = new Set();
const processedEvents = new Set();

function required(name) {
  const value = process.env[name];
  if (!value) {
    throw new Error(name + ' is required');
  }
  return value;
}

async function sha3Fetch(path, options = {}) {
  const response = await fetch(API_BASE_URL + path, {
    ...options,
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
      ...(options.headers || {}),
    },
  });

  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw new Error('sha3 ' + response.status + ': ' + JSON.stringify(body));
  }
  return body.data;
}

function verifySignature(rawBody, timestamp, nonce, signature) {
  if (!timestamp || !nonce || !signature) return false;

  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;
  if (seenNonces.has(nonce)) return false;

  const input = timestamp + '.' + nonce + '.' + rawBody;
  const expected = crypto
    .createHmac('sha512', IPN_SECRET)
    .update(input, 'utf8')
    .digest('hex');

  const actualBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expected, 'hex');
  if (actualBuffer.length !== expectedBuffer.length) return false;

  const valid = crypto.timingSafeEqual(actualBuffer, expectedBuffer);
  if (valid) seenNonces.add(nonce);
  return valid;
}

function eventKey(event) {
  const reference = event.deposit_id || event.withdrawal_id || event.user_id;
  return event.event + ':' + reference;
}

function originOf(url) {
  return new URL(url).origin;
}

async function recordSettledDeposit(externalUserId, event) {
  // Replace this with your durable notification or reconciliation workflow.
  console.log('Settled deposit for', externalUserId, event);
}

app.post('/sha3/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.get('x-timestamp');
  const nonce = req.get('x-nonce');
  const signature = req.get('x-signature');
  const eventHeader = req.get('x-event');

  if (!verifySignature(rawBody, timestamp, nonce, signature)) {
    return res.status(401).send('invalid signature');
  }

  let event;
  try {
    event = JSON.parse(rawBody);
  } catch {
    return res.status(400).send('invalid json');
  }

  if (eventHeader !== event.event) {
    return res.status(400).send('event mismatch');
  }

  const key = eventKey(event);
  if (processedEvents.has(key)) {
    return res.status(200).send('duplicate');
  }

  if (event.event === 'deposit.settled') {
    await recordSettledDeposit(event.user_id, event);
  }

  processedEvents.add(key);
  res.status(200).send('ok');
});

app.use(express.json());

app.post('/deposit-widget-sessions', async (req, res, next) => {
  try {
    const currencies = req.body.allowed_currencies || ['USDT_TRC20'];
    const data = await sha3Fetch('/v1/pay/deposit-widget-sessions', {
      method: 'POST',
      body: JSON.stringify({
        external_user_id: req.body.external_user_id,
        mode: 'embedded',
        allowed_currencies: currencies,
        allowed_origins: [originOf(PUBLIC_BASE_URL)],
        target_amount: req.body.target_amount,
        target_currency: req.body.target_currency,
        target_editable: Boolean(req.body.target_editable),
        tolerance_bps: req.body.tolerance_bps || 0,
        metadata: req.body.metadata,
      }),
    });

    res.json({
      deposit_widget_session_id: data.deposit_widget_session_id,
      client_secret: data.client_secret,
      hosted_url:
        FRONTEND_BASE_URL +
        data.hosted_url +
        '#client_secret=' +
        encodeURIComponent(data.client_secret),
      widget_script_url: FRONTEND_BASE_URL + '/widget.js',
      expires_at: data.expires_at,
    });
  } catch (error) {
    next(error);
  }
});

app.get('/deposits/:depositId', async (req, res, next) => {
  try {
    const deposit = await sha3Fetch('/v1/pay/deposits/' + encodeURIComponent(req.params.depositId));
    res.json(deposit);
  } catch (error) {
    next(error);
  }
});

app.use((error, _req, res, _next) => {
  console.error(error);
  res.status(500).json({ error: 'internal_error' });
});

app.listen(PORT, () => {
  console.log('Merchant integration listening on :' + PORT);
});

curl -X POST http://localhost:3000/deposit-widget-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "customer_123",
    "allowed_currencies": ["USDT_TRC20", "USDC_ETH"],
    "target_amount": "100.00",
    "target_currency": "USDT_TRC20",
    "target_editable": true,
    "tolerance_bps": 50
  }'

# Mount the returned deposit_widget_session_id and client_secret with the widget.
# For hosted redirect, open hosted_url in the customer's browser.
# Listen for deposit.settled on your webhook for every settled transfer.

<script src="https://www.sha3.net/widget.js"></script>
<div id="sha3-deposit"></div>
<script>
async function startDeposit() {
  const response = await fetch('/deposit-widget-sessions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      external_user_id: 'customer_123',
      allowed_currencies: ['USDT_TRC20'],
      target_amount: '100.00',
      target_currency: 'USDT_TRC20'
    })
  });
  const session = await response.json();

  window.Sha3Deposit.mount('#sha3-deposit', {
    sessionId: session.deposit_widget_session_id,
    clientSecret: session.client_secret,
    baseUrl: 'https://www.sha3.net',
    onProgress: event => console.log(event.progress),
    onSettled: event => console.log(event.deposit),
    onTargetReached: event => console.log(event.progress)
  });
}

startDeposit();
</script>

node - <<'NODE'
const crypto = require('node:crypto');

const secret = process.env.SHA3_IPN_SECRET;
const body = JSON.stringify({
  event: 'deposit.settled',
  deposit_id: 'dep_test',
  merchant_id: 1,
  user_id: 'smoke-test-user',
  amount: '10.000000',
  fee_amount: '0.100000',
  net_amount: '9.900000',
  status: 'settled',
  timestamp: new Date().toISOString(),
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const signature = crypto
  .createHmac('sha512', secret)
  .update(timestamp + '.' + nonce + '.' + body)
  .digest('hex');

console.log('curl -X POST http://localhost:3000/sha3/webhook \\');
console.log('  -H "Content-Type: application/json" \\');
console.log('  -H "X-Timestamp: ' + timestamp + '" \\');
console.log('  -H "X-Nonce: ' + nonce + '" \\');
console.log('  -H "X-Signature: ' + signature + '" \\');
console.log("  --data '" + body.replace(/'/g, "'\\''") + "'");
NODE