Authentication

The Partner API uses HMAC-SHA256 request signing. Each request is authenticated
by the API client id, timestamp, nonce, and signature.

Required Headers

Header	Required	Notes
`X-Partner-Client-Id`	Yes	Partner API client id issued by Oceafin.
`X-Partner-Timestamp`	Yes	Offset date-time, for example `2026-06-28T00:00:00Z`.
`X-Partner-Nonce`	Yes	Unique random value, at least 16 characters.
`X-Partner-Signature`	Yes	Lowercase hex HMAC-SHA256 signature.
`X-Request-Id`	Yes	Partner-generated request id for support correlation.
`Idempotency-Key`	Mutations only	Required for non-`GET` requests.

The timestamp must be within the server freshness window. A nonce cannot be
reused for the same client.

Compute the request body SHA-256 hash as lowercase hex. Use an empty string for
the body when the request has no body.

The signature base string is exactly:

METHOD
/partner/v1/path?raw=query
bodySha256Hex
X-Partner-Timestamp
X-Partner-Nonce
Idempotency-Key-or-empty-string

Rules:

METHOD is uppercase.

Use the raw path and raw query string exactly as sent on the wire.

Include the leading /partner/v1.

Do not include scheme, host, or fragment.

For GET, the final line is empty.

For mutations, the final line is the exact Idempotency-Key header value.

The final X-Partner-Signature value is:

lowercase_hex(hmac_sha256(clientSecret, signatureBaseString))

All mutations require Idempotency-Key.

Use a stable key for one partner action, not a new key for every retry. Good
examples:

cust-100001:kyc-submit:kyc-20260628-001
cust-100001:fiat-withdrawal:create:wd-9001
cust-100001:conversion:create:conv-7001

Behavior:

Same key and same request body returns the stored response.

Same key and different request body returns PARTNER_IDEMPOTENCY_CONFLICT.

A network retry should reuse the same key and the same request body.