# Quick Start - Your First Swap

Quote -> Build -> Sign -> Submit in four steps. Takes under 5 minutes if you have an API key and a signer.

### Step 1: Get a Quote

```bash
curl -X POST https://api.gateway.zert.com/api/v1/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": "solana",
    "toChain": "avax",
    "tokenIn": "SOL",
    "tokenOut": "WETH",
    "network": "mainnet",
    "amount": "100.00",
    "slippageBps": 75,
    "recipient": "0x1234567890123456789012345678901234567890"
  }'
```

The response includes a `routes` array. Each route has:

* `routeId` — pass this to Step 2
* `expectedAmountOut` — projected output for that route

### Step 2: Build the Signing Step

Swagger does not auto-fill `quoteId` and `routeId` from Step 1. Paste the fresh values from the previous quote response when testing in the docs UI.

```bash
curl -X POST https://api.gateway.zert.com/api/v1/swap/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "REPLACE_WITH_QUOTE_ID_FROM_POST_QUOTE",
    "routeId": "REPLACE_WITH_ROUTE_ID_FROM_SELECTED_ROUTE",
    "recipient": "0x1234567890123456789012345678901234567890",
    "waitForTxRequestMs": 300
  }'
```

Leave `Idempotency-Key` blank for one-off Swagger or curl calls. If you need retry-safe dedupe on direct HTTP calls, send your own UUIDv4 or ULID only when retrying the exact same payload. SDK and Postman flows can generate one automatically.

The response includes:

* `swapId` — use this for the rest of the flow
* `mode` — `sync` if the signable payload is ready now, `async` if you should poll
* `signing` — the signable payload when `mode` is `sync`

If the signing surface for the active step is not configured, the API returns `503` instead of a placeholder transaction payload.

### Step 3: Poll Until a Signable Payload Is Ready

If Step 2 returns `mode: "async"`, poll:

```bash
curl "https://api.gateway.zert.com/api/v1/swap/your-swap-id/signing" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When the response returns `mode: "sync"`, hand the payload to the external wallet or signer. Postman does not sign transactions.

### Step 4: Submit the Signed Artifact

```bash
curl -X POST "https://api.gateway.zert.com/api/v1/swap/your-swap-id/signing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rawTx": "0x_signed_tx_from_external_wallet"
  }'
```

If the execution has more than one signing step, keep polling the same endpoint until the next payload is ready.

### Track On-Chain Status (Optional)

```bash
curl "https://api.gateway.zert.com/api/v1/status/transaction/0x123...abc?chainRef=polygon-mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| Status      | Meaning                      |
| ----------- | ---------------------------- |
| `pending`   | Submitted, not yet confirmed |
| `confirmed` | Confirmed on chain           |
| `failed`    | Transaction failed           |

### What's Next

| Next step                                              | Go to                                                                                        |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Understand the full swap lifecycle in detail           | [Guides → Full swap flow](/integration-example/full-swap-flow.md)                            |
| Discover which chains, tokens, and pairs are available | [Guides → Discovery: chains, tokens, and pairs](/integration-example/discovery-and-quote.md) |
| Set up limit orders                                    | [Guides → Limit orders](/integration-example/limit-orders.md)                                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zert.com/getting-started/quick-start-your-first-swap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.