# Relay API routes

The SDK calls these routes for you, but they're a plain HTTP surface you can use
directly. All are **`POST`**, Turnkey-shaped, and authenticated with an `X-Stamp`
header (an API-key signature over the canonical request body).

::: info Base URL
Production: `https://api.kryard.com`. The SDK's `KryardRelayClient` targets this by
default.
:::

## Submit & track

| Route | Purpose |
| --- | --- |
| `POST /public/v1/relay/submit_transaction` | Submit a sponsored EIP-7702 transaction (authorization + batch). Returns a relay transaction record (`id`, `status`, `txHash`). |
| `POST /public/v1/relay/get_transaction` | Fetch a relay transaction by id. Poll until `status` is `confirmed`, `failed`, or `expired`. |

### Lifecycle states

`pending` → `broadcasted` → `confirmed`, or a terminal `failed` / `expired`. Gas is
**reserved** on submit and **debited at finality** (`confirmed`); a reorg clears the
recorded gas.

## Usage & balance

| Route | Purpose |
| --- | --- |
| `POST /public/v1/relay/billing_usage` | Native-gas usage rollup for the organization (metered relay spend). |
| `POST /public/v1/relay/token_usage` | ERC-20 gas usage rollup (`gas_token` / `gas_token_amount` per activity). |
| `POST /public/v1/relay/get_balance` | The organization's prepaid gas-tank balance (`deposited − debited − reserved`). |

## Operator

| Route | Purpose |
| --- | --- |
| `POST /admin/relay/deposit` | Top up an organization's prepaid gas tank. **Operator-only** — not part of the public org surface. |

## Authentication

Each request carries an `X-Stamp` header:

```
X-Stamp: base64url({ publicKey, scheme: "SIGNATURE_SCHEME_TK_API_P256", signature })
```

where `signature` is a P-256 signature over `SHA-256(canonical_json(body))`. Use the
SDK's `createApiKeyStamper`, or any compatible Turnkey-protocol stamper.