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 an 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 trade at status staged. Send a positive amount, which is the gross. The gateway takes the fee at ingress. Wallets must already be provisioned for the asset.

cURL

TS=$(date +%s)

BODY='{"entityId":"wallet-alice","counterpartyId":"wallet-bob","amount":1000,"currency":"USDC","reference":"INV-1042"}'

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 and status: "staged". 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`

The fee arithmetic is on Platform.

Sign real payloads with a sandbox key.

Request a key when you are ready.

Try Sandbox