Quickstart

Stage your first settlement in three steps.

This is a hands-on sketch against https://api.gutschow.xyz, not the complete API. For the path from reading to a live key, see Developers. For every operation and schema, use the API Documentation or download OpenAPI JSON. The open simulation needs no key: run GET/POST /api/v1/simulation. Sandbox keys (gsk_sandbox_…) issue after work-email verification on Sandbox.

1. Sign every write with your key and a Hash-Based Message Authentication Code (HMAC)

Settlement writes use a sandbox or live API key plus a timestamp-bound HMAC. Send the key as Authorization: Bearer or x-api-key. Sign timestamp.rawBody (Unix seconds, a dot, then the raw JSON body) with your HMAC secret, and send the hex as x-gutschow-signature. Send the timestamp, in Unix seconds, in x-gutschow-timestamp. The skew window is five minutes.

Header Purpose
Authorization Bearer gsk_sandbox_…
x-gutschow-timestamp Unix seconds at request time
x-gutschow-signature HMAC-SHA256 hex of timestamp.rawBody
Idempotency-Key Optional; also accepted on the JSON body

2. Stage a settlement

POST /v1/settlement/ingest (alias /api/v1/settlement/ingest) stages a USDC or EURC release at status staged. Send dispatchedAmount: the principal the payee is instructed to receive. The clearing toll is computed on that amount. Optional feePayer is sen (default), rec, or sha, and applies only with dispatchedAmount. Legacy amount is sender-pays (sen) only; do not send rec or sha with amount. Wallets must already be provisioned for the asset.

This sketch uses documentType commission_settlement (allowed on live keys). Live keys (gsk_live_…) accept only commission_settlement or agent_budget_release (otherwise 422). Sandbox keys may also use trade_settlement.

Releases at or above 1000 (USD or EUR equivalent) require originator and beneficiary metadata. The cURL below uses a dispatched amount under 1000. Field shape: OpenAPI JSON and Compliance.

Wallet, destination, and other dispatch fields required to stage live on the rail are in the OpenAPI ingest schema. This page does not list a corridor.

cURL

TS=$(date +%s)
BODY='{"entityId":"wallet-alice","counterpartyId":"wallet-bob","dispatchedAmount":150,"feePayer":"sen","currency":"USDC","reference":"INV-1042","documentType":"commission_settlement"}'
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SETTLEMENT_HMAC_SECRET" | awk '{print $2}')

curl -sS -X POST https://api.gutschow.xyz/v1/settlement/ingest \
-H "Authorization: Bearer $GUTSCHOW_API_KEY" \
-H "Content-Type: application/json" \
-H "x-gutschow-timestamp: $TS" \
-H "x-gutschow-signature: $SIG" \
-H "Idempotency-Key: inv-1042-1" \
-d "$BODY"

A successful call returns 201 with transaction_id, status: "staged", and fee_allocation. Staging does not reserve funds. A worker claims the row before rail confirmation. Poll GET /v1/settlement/status/{id} or wait for webhooks.

3. Verify each status webhook before you trust it

When status changes, Gutschow POSTs a signed event to your registered callback URL. Verify x-gutschow-outgoing-signature before you trust the body. Payload schemas and verification steps are in the API Documentation.

Example outbound body

{
"event": "settlement.status_changed",
"tenantId": "acme",
"transactionId": "c3f1a2b0-1111-2222-3333-444455556666",
"fromStatus": "processing",
"toStatus": "settled",
"timestamp": "2026-07-22T15:04:05.000Z",
"metadata": {}
}

Wallet and asset conventions

Rule Value
Wallet IDs Hyphenated, for example wallet-alice
Routable assets USDC, EURC

One clearing toll is computed on dispatched amount D. At Tier 0 (50 bps), the default rate is T = max(round(D × 0.005, 4), 1.00). That factor is not a universal rate for every partner; volume tiers and the $1.00 floor live at The toll and Toll schedule. Who bears the toll (sen / rec / sha) is at Who pays the clearing toll.

Same rails.
Two doors.

Sandbox

$0 to test.

Simulated clearing.
Work email required.

Production

From $900/month.

Live clearing.
License and toll apply.