GoldFin Open API v1

A server-to-server API for partners (distributors / integrators): gold custody accounts, XAUT physical redemption, balances, and withdrawals.

1. Introduction

The GoldFin Open API lets your platform plug into GoldFin's gold-asset layer: your users perform actions inside your product, and your system calls GoldFin via the API to hold, redeem, and settle gold.

1.1 What you can do with the API

1.2 Integration model (B2B2C)

You (the partner) register with GoldFin as a distributor account, and your end users are represented as ledger sub-accounts under your account. The API is called with your distributor identity: assets are booked in your main account and sub-accounts, and redemptions and withdrawals are initiated by your system.

Fee model: at redemption time GoldFin charges a service fee at the global rate — added on top of the redeemed amount, priced in gold weight, and deducted from your XAUT balance (e.g. at a 2% rate, redeeming 100g of physical gold deducts XAUT equivalent to 102g in total). The fee is shown transparently in the quote response (§5.4).

1.3 Prerequisites and onboarding flow

The API onboarding state machine has 4 states: not_started → sandbox_only → production_active (production is enabled directly by operations, with no pending-review intermediate state). Any enabled state can be frozen to suspended (API paused; on restore it returns to the state it was in before the freeze). See 8.1 State Machines. Key creation and management are done in the web Developer Console (/mine/api-keys).

2. Quickstart

# First request: GET /account (full signing example in §3.4)
curl -s "https://api-sandbox.goldfin.dev.stablehunter.ai/openapi/v1/account" \
  -H "X-GF-APIKEY: gfk_sandbox_xxxxxxxx" \
  -H "X-GF-TIMESTAMP: 1781136000000" \
  -H "X-GF-SIGNATURE: 9f2c…hex(HMAC_SHA256)…"

3. Authentication & Signing

Every request must carry an API key and an HMAC-SHA256 signature (modeled on Binance's approach). All three headers are required:

3.1 Signing string (signingString)

{timestamp}\n{METHOD}\n{path}\n{canonical_query}\n{sha256(body)}\n{idempotency_key_or_empty}

Exact rules for the six segments of the signing string

The signature = the lowercase hex of HMAC-SHA256(secret, signingString). Header names are never part of the signing string (HTTP header names are case-insensitive).

3.2 Time window (recvWindow)

A request may carry a recvWindow parameter (milliseconds, default 5000, max 60000). The server rejects requests where abs(serverTime − timestamp) > recvWindow → 401 GF_TIMESTAMP_OUT_OF_RANGE.

Time sync: GET /time returns the server's current time (unix milliseconds, same unit as X-GF-TIMESTAMP) and can be called without a signature — sync once when integrating, then periodically calibrate your local clock drift; when you hit GF_TIMESTAMP_OUT_OF_RANGE, call it first to rule out clock drift. The timestamp is a unix timestamp and has no inherent time zone, so no time-zone conversion is needed.

3.3 IP allowlist and key scopes

• Each key is bound to an IP allowlist: a source IP not on the list → 403 GF_IP_NOT_ALLOWED. Entries support a single IP or a CIDR range, up to 10 entries per key.
• An empty allowlist = no source-IP restriction; but a key with the withdraw scope must have a non-empty allowlist before it can be enabled (mirroring the exchange convention "enabling withdrawals requires an IP binding").
• Each key has scopes: read / redeem / withdraw / withdraw_approve / pickup_code; insufficient → 403 GF_SCOPE_INSUFFICIENT. withdraw initiates withdrawals, withdraw_approve approves large-amount reviews (these can be split across different keys to implement dual control); pickup_code (pickup authorization, bearer-grade) is independent of read and granted only to the presenting endpoint.
• Keys are scoped to sandbox / production environments: a cross-environment call → 403 GF_ENVIRONMENT_MISMATCH.
• The secret is shown only once at creation, so store it securely; rotation and revocation are supported (in the Developer Console).

3.4 Signing example (Python) and test vectors

import hmac, hashlib, time

def sign(secret, method, path, canonical_query, body: bytes, idem_key=""):
    ts = str(int(time.time() * 1000))
    body_hash = hashlib.sha256(body).hexdigest()          # raw bytes, lowercase hex
    signing = "\n".join([ts, method, path, canonical_query, body_hash, idem_key])
    sig = hmac.new(secret.encode(), signing.encode(), hashlib.sha256).hexdigest()
    return ts, sig

Official test vectors

Fixed test secret: gfsec_test_0123456789abcdef0123456789abcdef, fixed timestamp: 1750000000000. Verify your implementation against these first, then switch to a real secret — this is the first step in troubleshooting GF_SIGNATURE_INVALID.

4. Common Conventions

4.1 Environments & Base URL

Access entry points: the Open API is reachable only through the two official domains above — any other entry point (the main site domain, direct IP, etc.) returns 404. Sandbox and production are the same platform and the same API version, with fully isolated data: a sandbox key never sees production data, and vice versa.

Versioning: the URI carries the major version (/v1); within a version only backward-compatible incremental changes are made; breaking changes bump to /v2 and are announced in advance.

4.2 Idempotency (Idempotency-Key)

• Every POST that creates a funds-related resource must carry an Idempotency-Key header (≤64 chars, client-generated, ULID/UUID recommended).
• Replaying within 24 hours with the same key + the same body → returns the original first response (Stripe semantics).
• Same key + a different body → 409 GF_IDEMPOTENCY_CONFLICT.
• Dedup dimension: (api_key_id, environment, route, idempotency_key) (sandbox/production independent).
• Timeout-retry guidance: on request timeout / network interruption, when you're unsure whether it succeeded, resend with the same Idempotency-Key, byte-for-byte — if it already succeeded you get the original response back, otherwise it executes normally. This is the core purpose of idempotency; funds-related operations must be implemented this way, and you must never retry with a new key (which would cause a double charge).

Correct approach: serialize once, cache the raw bytes, and reuse the same bytes on retry (the signature also computes sha256(body) over these bytes, see §3.1) — do not JSON.stringify again on each retry.

// ✅ Correct: serialize the body once; bytes and Idempotency-Key stay constant across retries
const bodyBytes = Buffer.from(JSON.stringify({ quote_id: "q_123" }));  // done only once
const idemKey   = ulid();
const bodyHash  = sha256_hex(bodyBytes);                // goes into the signing string
async function send() {
  return http.post(url, bodyBytes, { headers: sign(bodyBytes, idemKey, bodyHash) });
}
await retryWithBackoff(send);   // every retry sends the same bodyBytes + the same idemKey

// ❌ Wrong: re-serialize on each retry — any difference in field order/whitespace/encoding → 409 GF_IDEMPOTENCY_CONFLICT
// await retryWithBackoff(() => http.post(url, JSON.stringify(payload), …));

4.3 Request tracing (X-GF-Request-Id)

Every response carries X-GF-Request-Id (a server-generated ULID), echoed in the error envelope's request_id field. Please provide this value when contacting technical support.

4.4 Pagination

List endpoints use limit (default 20, max 100) + offset (default 0), with the response envelope:

{ "items": […], "total_count": 123, "has_more": true }

Bounded small collections (deposit addresses, balances, order events) return only { "items": […] }, with no pagination fields — this is by design, not an omission.

4.45 Amounts, weight conversion, and precision

• All as strings: every amount / quantity field is a JSON string (never a number type), scientific notation is not accepted, and over-precision returns 400 GF_INVALID_REQUEST (no silent truncation).
• Weight conversion constant: 1 XAUT = 1 troy ounce = 31.1034768 grams (exact value). Grams ↔ ounces are converted using this constant throughout.
• Precision: gram quantities keep 3 decimal places; ounces are whole ounces; XAUT settlement keeps 8 decimal places (NUMERIC(28,8)). The service fee = redeemed amount × rate, rounded at the XAUT settlement precision using HALF-UP.
• Minimum units: gram bars min 100g, in integer multiples of 100g; ounce bars min 1oz, in whole ounces.
• No price risk: redemption is priced by gold weight (redeem 100g + 2% = XAUT equivalent to 102g) and does not move with the gold price — so there is no rounding residue arising from market movements; residue comes only from the rounding above.

4.5 Rate limits

Rate limiting is applied per api_key_id (sandbox/production counted independently). When limited → 429 + Retry-After, with X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset returned on the response.

Rate-limit tiers

v1 does not adopt Binance-style per-route weights (to be revisited once there is real load data); quotas are adjustable on the platform side and changes are announced in advance.

Minimal integration path (required / optional)

• Required: request signing (§3), timestamp/recvWindow, an Idempotency-Key on funds-related POSTs.
• Optional: webhooks — pure polling is a supported integration mode. Recommended polling intervals: in-flight orders/withdrawals every 10 seconds, steady-state lists/balances every 60 seconds (well within the rate limit).

4.6 Error handling

All errors return a uniform envelope (a rich error, intentionally separate from the flat errors of the existing /api/*):

{
  "error": {
    "code": "GF_QUOTE_EXPIRED",            // stable machine code; write your logic against this
    "message": "Quote has expired; request a new quote.",
    "request_id": "01J9X…",                // same as X-GF-Request-Id
    "doc_url": null,
    "details": null
  }
}

Error code table

Which errors are retryable

• Retryable: 5xx (server failures) and 429 (rate limit, honor Retry-After) — retry after backoff; when retrying funds-related POSTs you must reuse the same Idempotency-Key (see §4.2), otherwise you may double-charge.
• Do not retry: all other 4xx — the request itself is at fault; fix it and resend; blindly retrying a hundred times yields the same result.
• Two special cases: GF_QUOTE_EXPIRED → request a new quote, then place the order; GF_QUOTE_CONSUMED → check the order list first to confirm whether an order was already created, then decide the next step.

5.1 Account

Get the caller's API account profile: onboarding status, environment, KYB status, scopes, IP allowlist. Recommended as the first call after integrating, to verify connectivity and status.

Response fields

// 200
{
  "account_id": "acc_01J9X2M…",
  "owner_kind": "distributor",
  "api_status": "production_active",
  "environment": "production",
  "ip_allowlist": ["203.0.113.10"],
  "kyb_status": "approved",
  "permissions": ["read", "redeem", "withdraw"]
}

Transfer XAUT between a ledger sub-account and the main account, bidirectionally. sub_to_main: redemption requires XAUT in the main account — call this endpoint first when a quote/order returns GF_ASSET_IN_SUBACCOUNT. main_to_sub: return main-account funds to a specified sub-account — used to return a refund that landed in the main account back to the original end-user sub-account (the refund's refund.destination_sub_account_id is the suggested target). A transfer always requires you to explicitly specify the sub-account; GoldFin never selects or consolidates automatically.

Request body

// 201
{
  "transfer_id": "trf_01J9X3…",
  "asset": "XAUT", "amount": "2.5",
  "direction": "sub_to_main",
  "source_sub_account_id": "sub_8842",
  "status": "completed",            // a ledger-level operation, usually completes synchronously
  "created_at": "2026-06-11T08:00:00Z",
  "completed_at": "2026-06-11T08:00:00Z"
}

Errors

Query transfer status: pending → processing → completed | failed. On failure it returns failure_reason + error_code.

5.2 Funding (on-chain USDT / XAUT)

Get the account's on-chain deposit addresses (by asset / network). v1 deposits support on-chain USDT and direct XAUT deposits; fiat deposits are out of scope for v1. Deposit addresses belong to the account layer; once credited, assets can be partitioned to sub-accounts via the ledger (a bookkeeping-layer operation).

// 200
{ "items": [
  { "asset": "USDT", "network": "TRON", "address": "TX8c…", "memo": null },
  { "asset": "XAUT", "network": "ETH", "address": "0x9a…", "memo": null }
]}

List deposit records and crediting status (on-chain settlement status). Fields: deposit_id / asset / amount / source(=onchain) / status / tx_hash / created_at. Pair with the deposit.credited webhook to avoid polling.

5.3 Balances

Per-asset balances. Asset-center view: custody location is GoldFin's internal matter and is never exposed.

// 200
{ "items": [
  { "asset": "XAUT", "available": "12.5", "held": "15.0", "locked": "2.5", "compliance_hold": "0",
    "query_only": false, "redemption_eligible": true },
  { "asset": "GP", "available": "150000", "held": "150000", "locked": "0",
    "query_only": true, "redemption_eligible": false }
]}

5.4 RFQ / Quotes

Request an XAUT → physical redemption quote. Returns a quote_id + validity period; the price and service fee are snapshot-locked at quote time.

Request body

// 201 (includes "the four numbers")
{
  "quote_id": "qt_01J9X4…",
  "asset": "XAUT",
  "amount": "100", "unit": "gram",         // ① redeemed amount
  "fee_rate_pct": "2.0",                       // ② fee rate snapshot (global rate; API orders apply no GP offset)
  "service_fee_xaut": "0.0643",                // ③ service fee (= XAUT equivalent to 2g)
  "total_payable_xaut": "3.2794",              // ④ total payable (= XAUT equivalent to 102g, actually deducted at order time)
  "reference_price": "3342.10",                // reference price (XAUT/USD), display only
  "appointment_date": "2026-06-20",
  "expires_at": "2026-06-12T08:05:00Z",        // 5-minute validity
  "status": "open"      // open | consumed | expired
}

Errors

Query quote status (open / consumed / expired).

5.5 Redemption Orders

Create a redemption order, consuming a valid quote_id (binding the locked price). v1 applies no GP offset; the service fee is charged in full per the quote snapshot.

Request body

// 201
{
  "order_id": "ord_01J9X5…",
  "status": "pending",
  "asset": "XAUT", "amount": "100", "unit": "gram",
  "pickup_code": null,         // always null — the pickup code is only issued by POST .../pickup-code (requires the pickup_code scope), see the order-detail section
  "pickup_ref": "wsb-20260611-001",   // the reference number you passed in, echoed back
  "appointment_date": "2026-06-16",
  "refund": null,
  "created_at": "2026-06-11T08:01:30Z"
}

Errors

Paginated list of redemption orders — including orders placed on the web (the API is the complete view of the account's orders). Orders carry a source tag channel: api | web that you can filter on.

Order detail: status, pickup code, pickup location and time, completion and refund information. The 13 states are in 8.1 State Machines.

Order status-transition history (audit / reconciliation). Each event: from_status / to_status / at / actor. actor ∈ system | ops | partner — manual fallback operations (manual ops) also land in the event stream, ensuring status is queryable and reconcilable without relying on verbal sync.

Cancel a redemption order — cancellable only in the pending state (per the state machine). A non-cancellable state → 409.

5.6 Withdrawals (crypto only)

Withdraw idle balance (USDT / XAUT) to a pre-approved whitelisted address. Adding and reviewing whitelisted addresses is done on the web; v1 does not support fiat withdrawals. Flow: ① get a fee snapshot → ② place a withdrawal with the fee_token → ③ query status / receive a webhook.

// 200
{
  "asset": "USDT", "network": "TRON",
  "network_fee": "1.2",      // real-time network fee
  "platform_fee": "0.8",     // platform markup
  "total_fee": "2.0",
  "fee_token": "eyJ…sig",    // HMAC-signed, 120s TTL, sent back on POST /withdrawals
  "expires_at": "2026-06-11T08:03:00Z"
}

Request body

Errors

Withdrawal state machine: (pending_review →) approved → submitted → broadcasted → completed | rejected | failed, with tx_hash after completion. Small amounts (below the manual-review threshold) start directly from approved (the whitelisted address was pre-reviewed, so no per-withdrawal in-flight approval is needed); large amounts (≥ threshold, configurable per asset/network via system_config) first enter pending_review and require a key holding withdraw_approve or operations to approve via POST /withdrawals/{id}/approve (rejection → rejected).

5.7 GoldPoints GP (read-only)

GP (GoldPoint): 1 GP = 1mg of gold. In v1 the API only provides queries; earning and spending GP (converting to XAUT / cashing out) is done on the web.

{ "balance_gp": 150000, "query_only": true }   // 150000 GP = 150g of gold; this endpoint returns an integer, while GP in /balances is returned as a string (consistent with the other asset balance fields)

GP ledger: kind ∈ gp_earned | gp_redeemed, amount, at.

5.8 Referral (read-only)

{ "referred_count": 12, "query_only": true }

6. Webhooks

Key asynchronous events are pushed proactively, avoiding polling. All events use a uniform envelope:

{
  "event_id": "evt_01J9X6…",    // dedup key
  "event_sequence": 10342,        // global monotonic sequence; missed deliveries are replayed via GET /events?since_sequence
  "type": "redemption.order.status_changed",
  "created_at": "2026-06-11T08:05:00Z",
  "data": { /* resource snapshot, including the object version */ }
}

Event types (v1)

Event content data

{
  "data": {
    "object": { /* full resource snapshot — structurally identical to the corresponding GET endpoint's response */ },
    "previous_status": "payment_sent"  // carried only by *.status_changed events
  }
}

• data.object shares the same structure as the query endpoints: an order event carries the entire RedemptionOrder, a deposit event a Deposit, a withdrawal event a Withdrawal — one set of deserialization code serves both.
• pickup_code never appears in notifications (always null): the pickup code rotates roughly every 30 seconds and expires on delivery, and notification bodies end up in your server logs — the pickup code can only be obtained via the dedicated endpoint POST /redemption/orders/{id}/pickup-code (requires the pickup_code scope).
• Why there is no transfer event: transfers complete synchronously — the response of POST /account/transfers returns a terminal state on the spot (completed / failed); there is no "result arrives later" wait, so no notification is needed.

Delivery headers

Signature verification

• Compute HMAC-SHA256 over the raw bytes of "{timestamp}.{raw_body}" and compare it in constant time against the hex after v1= in the signature header (the v1= prefix is the signature-scheme version; future upgrades will add v2=, backward compatibly).
• Replay window 300 seconds: anything older is rejected.
• Dedup by event_id: delivery semantics are at-least-once.
• Determine state by version, not by arrival order: delivery is not guaranteed to be ordered. Each resource snapshot (order / withdrawal / transfer / deposit) carries a monotonically increasing version — apply an event only when its object.version is higher than the version you have stored, otherwise discard it. Never let webhook arrival order decide the final state, or out-of-order/re-deliveries will roll the state back to an old value.
• Missed deliveries are backstopped by event replay: each event carries a global monotonic event_sequence; when you miss a webhook, call GET /events?since_sequence={the highest sequence you've processed} to replay all missed events in one shot (the authoritative backstop, no per-resource polling needed). The ledger additionally carries a seq for line-by-line checking — under concurrent writes, an offset+limit list alone is not a reliable gap-detection method, so use the sequence.
• Verify the signature first, return 2xx quickly, and handle business logic asynchronously.
• The callback URL must be https (validated when configuring it in the console).

Retry schedule

After a delivery failure, retries occur at roughly 1 min / 5 min / 30 min / 2 hr / 6 hr / 24 hr / 24 hr, for 8 attempts total over about 3 days; after that it is marked failed, viewable in the Developer Console under "Recent deliveries". v1 does not provide manual re-send — when you do not receive an event, use the GET /events replay below as a backstop.

Event replay GET /events

Replay this account's event stream in ascending global event_sequence order — the same event objects pushed by webhooks — the authoritative backstop after a missed or out-of-order delivery. Cursor style: pass since_sequence = the highest sequence you've processed, and it returns the events after it + has_more; idempotent and repeatably readable.

// GET /events?since_sequence=10341&limit=100  → 200
{ "items": [
    { "event_id": "evt_…", "event_sequence": 10342, "type": "withdrawal.status_changed", "created_at": "…", "data": { /* same snapshot as the GET response */ } }
  ],
  "total_count": 1, "has_more": false
}

• While the account is suspended (API paused), delivery continues as usual (API pause only blocks new business creation, see §8.2 FAQ); delivery stops only on an account-level freeze.

How to configure

• Webhooks are configured in the Developer Console web app; v1 does not provide a webhook management API.
• Each environment (sandbox / production) has at most one callback URL, each with its own signing secret; the secret is shown only once at creation and can be rotated.
• The console lets you select which event types to subscribe to, provides a "Send test event" button, and lets you view recent deliveries (succeeded / failed / retrying).
• Advancing order status in the sandbox (see §7 test helpers) triggers webhooks as usual — signature verification and callback handling can be fully exercised in the sandbox.

7. Sandbox Guide

• Sandbox-first: enabling the API grants sandbox access, so you can create a sandbox key and start integrating immediately.
• Production keys can be created once production is enabled by operations (production_active).
• Sandbox and production use different keys and different Base URLs; a cross-environment call → 403 GF_ENVIRONMENT_MISMATCH.
• Production is enabled directly by operations (KYB must already be approved) → production_active; there is no pending-review intermediate state.

7.0 Sandbox shape and behavior

Sandbox and production are the same platform and the same API version (a test-mode shape, not a standalone environment) — the contract you validate in the sandbox is the production contract, with no version drift. There are only two differences: data is fully isolated, and all fund movements are simulated.

7.0.1 Test helper endpoints (sandbox-only; 404 under the production domain)

All three endpoints require an Idempotency-Key (same semantics as the production endpoints). Advancement is explicitly triggered rather than time-simulated — you can write the full loop (deposit → quote → order → advance to completed → receive webhook → reconcile) as an automated test case in your own CI, and failure branches (insufficient inventory, withdrawal failure, etc.) can be reproduced deterministically too.

7.1 Support & Appeals

• Technical support: email channel (address to be announced); please include X-GF-Request-Id and the timestamp in your message.
• Maintenance & availability: v1 does not yet provide maintenance-window announcements / a status page / SLA commitments.
• Account suspended: appeal via the support email, or contact your sales representative. After API access is restored, re-reconcile through the query endpoints.

8.1 State Machines

Redemption order (RedemptionStatus, 13 states, reusing the existing FSM)

• Only pending can be actively cancelled by the partner.
• pickup_code obtainable window: the three states confirmed / payment_pending / payment_sent, issued via POST .../pickup-code (requires the pickup_code scope) (a dynamic rotating code, ~30s lifetime, rotated on each issuance); after the gold service provider scans to redeem it is permanently hidden (latched, so it never reappears even if the state abnormally rolls back).
• Wire format is snake_case, exactly matching the existing system enums.

Funds-semantics table

Balance basis: held = total held, locked = amount frozen by active orders, available = held − locked. The fund action, what you should do, and what to show the end customer at each order state:

Push-timing tip: when you receive a status_changed to confirmed, you can notify the customer "you can go pick it up now" (with the appointment date and pickup location).

Transfer (AccountTransfer, 4 states)

Withdrawal (Withdrawal, 5 states)

API onboarding status (api_status, 4 states)

8.2 FAQ

GoldFin Open API v1 developer documentation