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

> ## Agent Instructions
> To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle).
> Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors).
> The API reference is generated from https://docs.agg.market/openapi/openapi.json.

# Custom domains

> Serve the AGG API, WebSocket and docs from your own domain, such as api.yourdomain.com

Your users can reach AGG on hostnames under your own domain instead of `agg.market`:

| What | Your hostname | Replaces |
| - | - | - |
| REST API | `api.<your domain>` | `api.agg.market` |
| WebSocket | `ws.<your domain>` | `ws.agg.market` |
| Docs | `docs.<your domain>`, or a name you choose such as `developers.<your domain>` | `docs.agg.market`, branded with your name, logo and colors |

You add DNS records once. AGG issues and renews the TLS certificates. Nothing changes in how
requests are authenticated: the same `x-app-id`, API keys and sessions work on both hostnames.

## 1. Set the domain in the admin dashboard

1. Open the [admin dashboard](https://admin.agg.market), pick your app, then open **Domains**
   under **Configure**.
2. **Step 1, Domain:** enter the parent name and click **Continue**. Use `yourdomain.com` to get
   `api.yourdomain.com`, or `trade.yourdomain.com` to get `api.trade.yourdomain.com`.
3. **Step 2, Developer docs:** choose **Yes** for branded docs at `docs.<your domain>`, or **No**
   for API and WebSocket only. Yes adds a third record. If `docs.<your domain>` already hosts your
   own docs, type another name in the box, such as `developers` (your domain is added for you,
   giving `developers.<your domain>`). It must be a single name, not `api` or `ws`. Set your logo
   and colors on the **Docs** page.
4. **Step 3, DNS records:** the dashboard lists the exact records to add, each with a copy button
   and a found or missing mark from the last check.

Finished steps fold into a summary. Use **Edit** on a step to change it later.

## 2. Add the DNS records

Add these at your DNS provider. The admin dashboard shows the same values for your app.

| Type | Name | Value |
| - | - | - |
| CNAME | `api.<your domain>` | `api.customers.agg.market` |
| CNAME | `ws.<your domain>` | `ws.customers.agg.market` |
| CNAME | `docs.<your domain>` (or the docs hostname you chose) | `docs.customers.agg.market` (only with developer docs on) |
| TXT | `_agg-challenge.<your domain>` | Only if the dashboard asks for it (see below) |

For Cloudflare, GoDaddy, IONOS, Squarespace and Namecheap, the provider buttons in step 3 can
help you add the records. Choose **Your DNS provider** for anything else, and add them by hand.

> [!WARNING]
>
> The records must point straight at AGG.
>
> * **Cloudflare:** set each record to **DNS only** (grey cloud). A proxied (orange cloud) record
>   stops the certificate from being issued.
> * **CAA records:** if your domain has any, add one that allows `amazon.com`. Otherwise the
>   certificate request is refused.
> * **No other records on those names.** Remove any existing A, AAAA or CNAME on `api.`, `ws.` or
>   your docs hostname before adding these.

### Prove ownership (TXT record)

You only need the TXT record when the hostname is already set on another AGG app, for example
when you move a domain from a test app to your production app. The dashboard then shows
**Prove ownership** with the TXT value. Add it, then click **Check now**.

## 3. Wait for Active

Click **Check now** after adding the records. The status moves through these steps:

| Status | Meaning |
| - | - |
| Waiting for DNS | AGG can't see the records yet. DNS changes can take a while to spread. |
| Prove ownership | Add the TXT record shown in the dashboard. |
| DNS verified | The records are correct. |
| Issuing certificate | AGG is issuing the TLS certificate for your hostnames. This usually takes a few minutes. |
| Active | Your hostnames are live. |
| DNS needs attention | A record changed or was removed after setup. The dashboard shows which one. |
| Suspended | The domain is turned off. Contact AGG. |

## 4. Point your app at your hostnames

Once the status is **Active**, switch your client to your hostnames:

```ts SDK theme={null}
import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.yourdomain.com",
  wsUrl: "wss://ws.yourdomain.com/ws",
  appId: "your-app-id",
});
```

```bash cURL theme={null}
curl https://api.yourdomain.com/app/config \
  -H "x-app-id: your-app-id"
```

The cURL call is a quick check that your API hostname answers:
[Get the per-app UI config](https://docs.agg.market/api-reference/markets/get-the-per-app-ui-config-disabled-venues-+-categories.md).

Your website's own origin (for example `https://yourdomain.com`) still has to be in **Approved
domains** on the same page. Browser calls from an origin that isn't listed are rejected, whichever
API hostname they use. If you want the docs playground to send requests, add
`https://docs.<your domain>` there too.

A custom hostname only serves the app it was set on. A request to `api.yourdomain.com` with
another app's `x-app-id` is rejected.

## Remove a domain

Click **Remove custom domain** under the steps. AGG stops serving your hostnames and
releases their certificates. Switch your app back to `api.agg.market` and `ws.agg.market` first,
then delete the DNS records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.