Skip to main content

Client libraries

There is no published CashXChain SDK. The API is HTTPS and JSON, and a client for it is small: the Quickstart script is a complete one in about sixty lines of TypeScript or Python.

Generate types from the spec​

The OpenAPI document is served by the sandbox and describes production too:

Bash
curl -s https://api.sandbox.cashxchain.com/v1/openapi.json -o cxc-openapi.json
npx openapi-typescript cxc-openapi.json -o cxc-api.d.ts

Any OpenAPI generator works. Check the coverage notes first — a few routes are missing from the spec, and where the spec and the route reference disagree, the reference is right.

What a client must do​

These are easy to build in on day one and painful to retrofit:

  1. Send an Idempotency-Key on every write that takes one, and reuse it on every retry of that write. Derive it from your own record — the invoice, the payment run — not from a fresh random value per attempt. See Idempotency.
  2. Branch on the HTTP status and the error code, never on message. Expect a few errors to be plain text rather than JSON. See Errors.
  3. Log X-Request-Id with every call you make. It is how you and support find a request later. See Request IDs and logs.
  4. Treat a payout as final only when its status says so — settled, failed, cancelled or returned. 202 means accepted. See Payouts.
  5. Retry 5xx and 429 with backoff, honouring Retry-After, and never with a new idempotency key. See Rate limits.
  6. Verify webhook signatures over the raw body. See Webhooks.
  7. Keep the base URL and the key in configuration — switching environment is changing those two values. See Environments.
  8. Validate the key's checksum at start-up, so a truncated secret fails loudly. See Key format.