Authentication

The API key header

Authenticate every request with your secret API key in the X-Api-Key header:

X-Api-Key: zp_live_sk_a1b2c3d4e5f60718_0123456789abcdef0123456789abcdef0123456789abcdef

Use X-Api-Key — not Authorization

On the public integration surface (/v1/deposit-addresses, /v1/deposits, /v1/webhooks), the only accepted carrier is the X-Api-Key header. An Authorization: Bearer … header on these routes is treated as a dashboard (JWT) login and will be rejected with 401. Always send your key in X-Api-Key.

A missing or malformed key returns 401 with code INVALID_API_KEY.

Key format

Kind	Shape
Public key	zp_<env>_pk_<keyId>
Secret key	zp_<env>_sk_<keyId>_<secret>

• <env> is test or live.
• <keyId> is 16 hex chars (a non-secret lookup id).
• <secret> is 48 hex chars (192 bits of entropy).
• Only an argon2 hash of the secret is stored server-side. The raw secret key is shown exactly once at creation — store it somewhere safe; it can't be retrieved again, only rotated.

Test vs live

The environment is baked into the key (zp_test_… vs zp_live_…) and stored on the key record; the two are cross-checked on every request, so a test key can never be replayed as live (or vice versa). Use:

Environment	Base URL	Settles on
test	https://api-test.zaropay.com	TRON testnet (Nile)
live	https://api.zaropay.com	TRON mainnet

IP allowlist (optional)

Each key can carry an IP allowlist (individual IPs and/or CIDR ranges), configured in the dashboard.

• Empty allowlist = no restriction.
• A non-empty list rejects requests from any other IP with 403 IP_NOT_ALLOWED. The error message echoes the IP ZaroPay saw, so you know exactly what to add.
• It fails closed: if the client IP can't be determined, the request is rejected.

Lock production keys to your server's egress IP(s) for defence in depth.

Rate limits

Requests are rate-limited at the gateway (fixed 60-second windows):

Tier	Limit	Scope
Per-key	120 req / min	Your confirmed API key (raise on request)
Per-IP	600 req / min	DoS floor across all /v1 traffic

On success you get RateLimit-Limit and RateLimit-Remaining headers. On breach you get 429 Too Many Requests with a Retry-After header (seconds) — back off and retry.

Keep secrets server-side

API keys and webhook signing secrets are server-side credentials. Never embed them in browser JavaScript, mobile apps, or anything shipped to a customer. All ZaroPay API calls should originate from your backend.