Developer Documentation

Integrate sha3 into your application to accept cryptocurrency payments. Merchant access is onboarding-controlled: complete account setup and any required review before using issued API credentials for server-to-server calls.

Quick Start

Create a merchant account and submit your business details to begin onboarding
Complete any required review before relying on issued API Keys or IPN Secrets in production
Use the API Key in the X-API-Key header for approved payment endpoints
Create orders, get deposit addresses, and verify webhook signatures using your IPN Secret

API Key

Your key is only used in-browser and never stored.

Quick Select

https://api.sha3.net

All payment API calls require an API Key sent in the X-API-Key header. API keys are activation-gated and should only be treated as usable after the merchant account has completed the required onboarding and review steps.

API Key (Server-to-Server)

Include your API key in every request to /v1/pay/ endpoints.

http

GET /v1/pay/deposit-address?user_id=user123&currency=USDT_TRC20
Host: api.sha3.net
X-API-Key: your-api-key-here

⚠️ Never expose your API Key in client-side code. All payment API calls should be made from your server.

Onboarding is controlled. Creating an account does not automatically mean the merchant is approved for unrestricted production use, payouts, or live credential issuance.

API Key Format

API keys are random alphanumeric strings. They are stored as SHA-256 hashes in the database — the raw key is only shown once at creation time. Keep it secure.

sha3 follows the Google JSON Style Guide. Success and failure are indicated by HTTP status codes — there is no top-level success or ok field.

✅ Success (HTTP 2xx)

json

{
  "data": {
    "order_id": "abc-123",
    "status": "pending"
  }
}

❌ Error (HTTP 4xx / 5xx)

json

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be positive"
  }
}

• Always check HTTP status code first: 2xx = success, 4xx/5xx = error

• error.code is a machine-readable string constant (e.g. INVALID_CURRENCY) — use it for programmatic error handling

• error.message is human-readable, may change — do not match on it

• Amounts are always decimal strings (e.g. "10.000000"), never floats

Environment	API (Gateway)
Production	`https://api.sha3.net`

• API (Gateway) — single public entry point for all /v1/pay/ endpoints. Production sits behind CloudFront for edge caching and DDoS protection.

• Portal API is an internal service (no public ingress). All portal routes go through the Gateway at /v1/portal/.

• checkout_url returned by order creation is a relative path (e.g. /checkout/<order_id>). Prepend your frontend domain to build the full URL.

• Sandbox is not exposed as a separate public environment today. Chain-backed tests require a real observed transfer on the selected production network, so start with the smallest safe stablecoin amount.

These endpoints require the X-API-Key header. All payment endpoints use the /v1/pay/ prefix.

Order amounts are token-denominated. amount: "10.00" with currency: "ETH" means 10 ETH, not 10 USD converted to ETH. The current order API does not create fiat quotes, apply FX/slippage logic, or enforce exact amount matching at settlement, so production checkout should use stablecoin amounts unless pricing is handled merchant-side.

POST/v1/pay/orders🔐 API Key

Create a new payment order. Returns a checkout URL that you can redirect your customer to.

Request Body

Parameter	Type	Required	Description
`amount`	string	Required	Order amount as a decimal string in the unit of currency (e.g. "10.00" USDT for USDT_TRC20)
`currency`	string	Required	Crypto currency code (e.g. "USDT_TRC20", "ETH"). No fiat conversion or quote is created. Use GET /v1/currencies for the full list.
`description`	string	Optional	Order description shown on the checkout page
`metadata`	object	Optional	Arbitrary key-value metadata (your internal order ID, user info, etc.). Returned by the order API; not included in the current order.paid webhook payload.
`redirect_url`	string	Optional	URL to redirect after successful payment
`cancel_url`	string	Optional	URL to redirect on cancellation

bash

curl -X POST https://api.sha3.net/v1/pay/orders \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "currency": "USDT_TRC20",
    "description": "Premium Plan",
    "metadata": {
      "merchant_order_id": "INV-10001",
      "customer_id": "cus_123"
    },
    "redirect_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  }'

Response

json

{
  "data": {
    "order_id": "ord_550e8400-e29b-41d4-a716-446655440000",
    "checkout_url": "/checkout/ord_550e8400-e29b-41d4-a716-446655440000",
    "expires_at": "2026-02-25T12:00:00Z"
  }
}

💡 checkout_url is a relative path. Prepend your frontend domain to get the full URL, e.g. https://www.sha3.net/checkout/...

GET/v1/pay/orders/{order_id}🔐 API Key

Get order details by ID.

bash

curl https://api.sha3.net/v1/pay/orders/ord_550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

Response

json

{
  "data": {
    "order_id": "ord_550e8400-e29b-41d4-a716-446655440000",
    "amount": "10.00",
    "currency": "USDT_TRC20",
    "status": "pending",
    "selected_crypto": null,
    "deposit_address": null,
    "deposit_id": null,
    "description": "Premium Plan",
    "metadata": {
      "merchant_order_id": "INV-10001",
      "customer_id": "cus_123"
    },
    "redirect_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "expires_at": "2026-02-25T12:00:00Z",
    "created_at": "2026-02-25T11:00:00Z",
    "updated_at": "2026-02-25T11:00:00Z"
  }
}

GET/v1/pay/orders🔐 API Key

List orders for the authenticated merchant.

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: pending, paid, expired
`limit`	integer	Optional	Max results (default: 20, max: 100)
`offset`	integer	Optional	Pagination offset (default: 0)

POST/v1/pay/orders/{order_id}/select🔐 API Key

Select the cryptocurrency for an order. This is called by the hosted checkout page when the customer picks their payment currency — you typically do not need to call this directly.

Parameter	Type	Required	Description
`currency`	string	Required	Supported crypto currency code (e.g. "USDT_TRC20", "ETH"). Selection allocates an address; it does not quote fiat or change the stored order amount.

Response

json

{
  "data": {
    "order_id": "ord_550e8400-...",
    "status": "pending",
    "selected_crypto": "USDT_TRC20",
    "deposit_address": "TXqH4v...",
    ...
  }
}

GET/v1/pay/deposit-address🔐 API Key

Get or allocate a permanent deposit address for a user. The same user always gets the same address (idempotent). Addresses are assigned from the address pool or generated on-demand via the wallet service.

Parameter	Type	Required	Description
`user_id`	string	Required	Unique user identifier in your system
`currency`	string	Required	Currency code (e.g. "USDT_TRC20", "ETH")

bash

curl "https://api.sha3.net/v1/pay/deposit-address?user_id=user123&currency=USDT_TRC20" \
  -H "X-API-Key: your-api-key"

Response

json

{
  "data": {
    "address": "TXqH4v...",
    "currency": "USDT_TRC20",
    "network": "tron",
    "chain_id": 728126428,
    "user_id": "user123",
    "created_at": "2026-02-25T10:30:00Z"
  }
}

GET/v1/pay/deposits🔐 API Key

List deposits for the authenticated merchant.

Parameter	Type	Required	Description
`user_id`	string	Optional	Filter by user ID
`limit`	integer	Optional	Max results (default: 20, max: 100)
`offset`	integer	Optional	Pagination offset (default: 0)

Response

json

{
  "data": {
    "deposits": [
      {
        "deposit_id": "dep_abc123",
        "user_id": "user123",
        "address": "TXqH4v...",
        "currency": "USDT_TRC20",
        "chain_id": 728126428,
        "tx_hash": "0xabc...",
        "amount": "100.000000",
        "fee_amount": "1.000000",
        "net_amount": "99.000000",
        "status": "settled",
        "created_at": "2026-02-25T10:00:00Z",
        "confirmed_at": "2026-02-25T10:05:00Z",
        "settled_at": "2026-02-25T10:05:10Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

GET/v1/pay/deposit/{deposit_id}🔐 API Key

Get a specific deposit by ID.

GET/v1/pay/balance🔐 API Key

Get the merchant's balance across all currencies. Available is spendable; frozen is held pending withdrawal completion.

json

{
  "data": {
    "balances": [
      { "currency": "USDT_TRC20", "chain_id": 728126428, "available": "1250.50", "frozen": "0.00" },
      { "currency": "ETH", "chain_id": 1, "available": "0.85", "frozen": "0.10" }
    ]
  }
}

POST/v1/pay/withdrawals🔐 API Key

Create a withdrawal request. The amount is immediately frozen from available balance. Withdrawals within configured limits auto-approve; larger amounts stay pending until signer approval, then move through broadcasting → processing → completed.

Request Body

Parameter	Type	Required	Description
`to_address`	string	Required	Destination wallet address (EIP-55 checksum for EVM chains)
`chain_id`	integer	Required	Target blockchain chain ID (e.g. 728126428 for Tron, 1 for Ethereum)
`token_address`	string	Optional	Token contract address. Omit or set null for native coins (ETH, TRX)
`amount`	string	Required	Amount as a plain decimal string in token units (e.g. "100.000000" for USDT or "0.5" for ETH). Scientific notation and wei-style smallest-unit integers are not accepted.

bash

curl -X POST https://api.sha3.net/v1/pay/withdrawals \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "TXqH4v...",
    "chain_id": 728126428,
    "token_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "100.000000"
  }'

Response

json

{
  "data": {
    "id": 42,
    "to_address": "TXqH4v...",
    "chain_id": 728126428,
    "token_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "100.000000",
    "fee_amount": "0",
    "status": "pending",
    "tx_hash": null,
    "confirmations": 0,
    "error_msg": null,
    "requested_at": "2026-02-25T10:00:00Z",
    "approved_at": null,
    "completed_at": null,
    "created_at": "2026-02-25T10:00:00Z"
  }
}

⚠️ Withdrawals exceeding your account's single-tx or daily limits stay pending until approval is submitted through POST /v1/withdrawals/{id}/approve with a signer key. Approved withdrawals then progress through broadcasting and processing before completion. If the platform cannot determine the broadcast outcome, the frozen balance remains held while the sha3 operations team verifies the chain result.

GET/v1/pay/withdrawals🔐 API Key

List withdrawals for the authenticated merchant.

Parameter	Type	Required	Description
`status`	string	Optional	Filter by merchant-visible status: pending, approved, broadcasting, processing, completed, failed
`limit`	integer	Optional	Max results (default: 20, max: 100)
`offset`	integer	Optional	Pagination offset (default: 0)

Response

json

{
  "data": {
    "withdrawals": [...],
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

GET/v1/pay/withdrawals/{id}🔐 API Key

Get a specific withdrawal by numeric ID.

POST/v1/withdrawals/{id}/approve🔐 Signer Key

Approve or reject a pending withdrawal using a signer key. This route is only for configured signers and only works while the withdrawal is still pending.

Required Header

http

X-Signer-Key: sk_live_xxx

Request Body

Parameter	Type	Required	Description
`action`	string	Required	Either approve or reject
`comment`	string	Optional	Optional reviewer comment stored with the approval record
`chain_id`	integer	Required	Chain id used when resolving the applicable multisig policy
`token_address`	string	Optional	Token contract address for token withdrawals; omit or null for native assets

bash

curl -X POST https://api.sha3.net/v1/withdrawals/42/approve \
  -H "X-Signer-Key: your-signer-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "comment": "Within treasury policy",
    "chain_id": 728126428,
    "token_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
  }'

Rejecting a pending withdrawal moves it to failed and refunds the frozen balance back to available.