DEVELOPER DOCS

API DOCUMENTATION

Integrate SafeHash's secure payment verification into your applications

DEMO DOCUMENTATION

All webhooks, API endpoints, and code examples shown on this page are for demonstration purposes only. For actual API connections, integration codes, and production access, you must obtain your API keys. Contact us to get your API keys.

INTRODUCTION

The SafeHash API allows you to programmatically create payment gateways, monitor transactions, and receive webhook notifications. All API access is over HTTPS and accessed from https://api.safehash.io/v1.

BASE URL

https://api.safehash.io/v1

TLS 1.3 Encryption

99.99% Uptime

<100ms Response

AUTHENTICATION

Authenticate your API requests using your API key. Include your API key in the Authorization header of all requests.

BASH

curl https://api.safehash.io/v1/gateways \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Keep your API keys secure!

Never expose API keys in client-side code or public repositories. Use environment variables on your server.

API KEY TYPES

Key Type	Prefix	Usage
Live Secret Key	`sk_live_`	Production transactions
Test Secret Key	`sk_test_`	Testing & development
Publishable Key	`pk_`	Client-side (limited access)

QUICK START

Get started with SafeHash in just a few steps:

Get your API keys

Create a gateway

Generate a gateway address for receiving payments.

Set up webhooks

Configure webhooks to receive payment notifications.

CREATE YOUR FIRST GATEWAY

JAVASCRIPT

const response = await fetch('https://api.safehash.io/v1/gateways', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    network: 'ethereum',
    destination_address: '0xYourWalletAddress...',
    label: 'My First Gateway'
  })
});

const gateway = await response.json();
console.log(gateway.gateway_address);
// Returns: 0xSafeHashGeneratedAddress...

ERROR HANDLING

SafeHash uses conventional HTTP response codes to indicate success or failure of API requests.

Code	Description
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Rate Limited - Too many requests
`500`	Server Error - Something went wrong

ERROR RESPONSE

{
  "error": {
    "code": "invalid_destination",
    "message": "The destination address is not a valid Ethereum address",
    "param": "destination_address",
    "doc_url": "https://docs.safehash.io/errors/invalid_destination"
  }
}

GATEWAYS

Gateways are the core of SafeHash. Each gateway provides a unique address for receiving verified payments.

POST /v1/gateways

Create a new payment gateway

PARAMETERS

Parameter	Type	Required	Description
`network`	string	Yes	ethereum, bitcoin, solana, bnb, tron, monero
`destination_address`	string	Yes	Your wallet address for receiving funds
`label`	string	No	Friendly name for the gateway
`webhook_url`	string	No	URL for payment notifications

GET /v1/gateways

List all your gateways

GET /v1/gateways/:id

Retrieve a specific gateway

DELETE /v1/gateways/:id

Deactivate a gateway

TRANSACTIONS

Query and monitor transactions processed through your gateways.

GET /v1/transactions

List all transactions

QUERY PARAMETERS

Parameter	Type	Description
`gateway_id`	string	Filter by gateway
`status`	string	pending, verified, forwarded, blocked
`limit`	integer	Number of results (max 100)
`starting_after`	string	Cursor for pagination

RESPONSE

{
  "data": [
    {
      "id": "tx_1abc2def3ghi",
      "gateway_id": "gw_xyz789",
      "status": "forwarded",
      "network": "ethereum",
      "token": {
        "symbol": "USDT",
        "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "amount": "1000.00",
        "verified": true
      },
      "from_address": "0x...",
      "forwarded_tx": "0x...",
      "created_at": "2026-03-24T10:30:00Z"
    }
  ],
  "has_more": true
}

VERIFICATION

Check the verification status and security analysis of tokens.

GET /v1/verify/:network/:contract

Get verification status of a token contract

RESPONSE

{
  "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "network": "ethereum",
  "symbol": "USDT",
  "name": "Tether USD",
  "verified": true,
  "risk_score": 5,
  "checks": {
    "contract_verified": true,
    "honeypot": false,
    "blacklisted": false,
    "liquidity_sufficient": true,
    "trading_history": true
  },
  "last_checked": "2026-03-24T10:00:00Z"
}

WEBHOOKS

Receive real-time notifications for payment events.

WEBHOOK EVENTS

Event	Description
`payment.received`	Payment received at gateway address
`payment.verifying`	Token verification in progress
`payment.verified`	Token verified as legitimate
`payment.forwarded`	Funds forwarded to destination
`payment.blocked`	Scam token blocked

WEBHOOK PAYLOAD

{
  "id": "evt_1abc2def",
  "type": "payment.forwarded",
  "created": 1711276200,
  "data": {
    "transaction_id": "tx_1abc2def3ghi",
    "gateway_id": "gw_xyz789",
    "amount": "1000.00",
    "token_symbol": "USDT",
    "forwarded_tx": "0x..."
  }
}

VERIFYING WEBHOOKS

All webhook payloads include a signature in the X-SafeHash-Signature header. Verify this signature using your webhook secret to ensure authenticity.

SDKs & LIBRARIES

Official client libraries for popular programming languages:

JavaScript / Node.js

npm install @safehash/sdk

Python

pip install safehash

Go

go get github.com/safehash/safehash-go

PHP

composer require safehash/sdk

RATE LIMITS

Plan	Requests/minute	Requests/day
Starter	60	10,000
Professional	300	100,000
Enterprise	Custom	Unlimited

READY TO BUILD?

Get your API keys and start integrating SafeHash today

GET API KEYS