> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trustware.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authentication, base URL, and the four-step integration pattern for the Trustware REST API.

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.

<Note>
  **SDK vs. API:** If you're building a React app and want a prebuilt deposit widget, start with the [SDK introduction](/introduction). If you're building server-side, using a custody wallet, or need direct control over transaction signing and submission, use this API.
</Note>

## Base URL

```
https://api.trustware.io
```

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.

```js theme={null}
const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TW_KEY,
  },
  body: JSON.stringify(payload),
});
```

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.

<Warning>
  Never expose your API key in client-side code. Store it in an environment variable and make Trustware API calls from your backend.
</Warning>

## Integration pattern

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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, check the spender allowance with [`GET /allowance`](/api-reference/allowance) and prompt the user for an approval transaction if needed before broadcasting the route.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## 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. If you exceed the limit, the response returns `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Implement exponential backoff on `429` responses, especially on the `/status` polling endpoint.

## 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.