Skip to main content
The Trustware REST API is the backend integration path. Use it when you need server-side control over signing, when you’re running a custody wallet, or when you’re building outside of React. It is a REST API served over HTTPS. All requests use JSON bodies and return JSON responses. Authentication is via an API key passed in a request header.
SDK vs. API: If you’re building a React app and want a prebuilt deposit widget, start with the SDK introduction. If you’re building server-side, using a custody wallet, or need direct control over transaction signing and submission, use this API.

​
Base URL

All endpoint paths below are relative to this base URL. Use the /api/v1/ path prefix. Legacy /api/ aliases exist but are sunset on 2026-12-31.

​
Authentication

Pass your API key in the X-API-Key header on every request.
API keys can be origin-locked to a specific domain so they cannot be used from unauthorized origins. Contact Trustware to configure origin locking for your key.
Never expose your API key in client-side code. Store it in an environment variable and make Trustware API calls from your backend.

​
Integration pattern

Every integration follows the same pattern regardless of source chain or use case:
1

Quote (optional)

Call POST /api/v1/routes/quote to get a fee estimate and expected output before the user confirms. AML/OFAC screening runs at this step. If the call returns an error, no funds move.
2

Route

Call POST /api/v1/routes/route to generate the full transaction payload. Pass a metadata object with any fields you need echoed back in status responses (user ID, withdrawal ID, etc.). An intent record is created internally.To deposit into a contract rather than pay a recipient address, add hooks.postHook to the request. See vault destinations.
3

Sign and broadcast

Your signing infrastructure (custody wallet, MetaMask, or equivalent) builds the transaction from the payload, signs it, and broadcasts it to the source chain. Trustware never touches private keys.If the source token is an ERC-20, grant any allowances the route requires before broadcasting it. When the route response includes route.execution.approvals, each entry gives the token, spender, and exact amount to approve. See token approvals.
4

Receipt and status

Immediately submit the transaction hash to POST /api/v1/route-intent/:id/receipt. Then poll GET /api/v1/route-intent/:id/status until the status reaches success or failed.

​
What Trustware does not do

Trustware never takes custody of funds. The API generates a transaction payload that your signing infrastructure executes. Private keys stay with you. Funds flow peer-to-peer via on-chain contracts. Trustware is the routing and orchestration layer, not a custodian.

​
Rate limits

The API is rate-limited per API key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 Too Many Requests adds Retry-After. Retry on the schedule those headers state. The limit is a fixed window, so a delay of your own either lands inside the same window and fails again, or waits longer than Retry-After already told you. On the /status polling loop, watch X-RateLimit-Remaining and use next_poll_at to space your requests.

​
Request IDs

Every response carries an X-Request-Id header holding a UUID that Trustware assigns to the call. Quote it in support requests. It is the same value returned as request_id on the status payload, and error responses repeat it in the body alongside error. Trustware always generates this ID, so an X-Request-Id you send is ignored. POST /api/v1/routes/route and POST /api/v1/routes/deposit-address also return X-Provider-Request-Id, the routing provider’s own correlation ID for the route they served. The two IDs are separate, so keep both when you log a route call. Browser clients read the provider ID from route.requestId in the response body rather than the header, which is not CORS-exposed; it reaches the status payload as provider_request_id.

​
Versioning

The current API version is v1. Breaking changes will introduce a new version prefix. The legacy /api/ (unversioned) aliases will return deprecation headers and stop working on 2026-12-31.