> For the complete documentation index, see [llms.txt](https://docs.anchored.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anchored.finance/trading-api/guides/quickstart-first-trade.md).

# Quickstart: First API Trade

This guide walks through the smallest API flow for a partner integration:

1. Discover a tradable stock.
2. Confirm `mUSD`.
3. Deposit if needed.
4. Place a market buy.
5. Record and track the transaction.
6. Confirm the portfolio changed after settlement.

Use this as the smoke test before adding limit orders, withdrawals, or One Click.

## Flow

```mermaid
flowchart TB
    A[Configure API key] --> B[GET symbols]
    B --> C[Pick tradable symbol]
    C --> D[GET user balance]
    D --> E{Enough mUSD}
    E -->|no| F[Approve cash token]
    F --> G[Deposit cash]
    G --> H[Wait for mUSD]
    E -->|yes| I[Build market buy calldata]
    H --> I
    I --> J[Submit router transaction]
    J --> K[Record txHash]
    K --> L[Wait for orderId]
    L --> M[Poll order detail]
    M --> N[Confirm portfolio]
```

## 1. Configure Request Context

Every request must include:

| Header           | Example                             |
| ---------------- | ----------------------------------- |
| `x-api-key`      | Partner API key                     |
| `x-api-ts`       | Current Unix milliseconds           |
| `x-api-nonce`    | UUID                                |
| `x-api-sign`     | HMAC-SHA256 authentication value    |
| `x-api-chain-id` | `8453`, `143`, `1`, or target chain |
| `x-api-p`        | `Anchored` for the Anchored API     |

Use the exact `/api/v1/...` path in the HMAC payload. Do not include the domain or `/rwa/trading`.

## 2. Discover a Tradable Stock

```
GET /api/v1/symbols
```

Pick an item where `tradable` is `true`. Relevant response fields:

| Field             | Use                               |
| ----------------- | --------------------------------- |
| `symbol`          | Symbol and quote lookup           |
| `contractAddress` | `stockAddress` for order requests |
| `price`           | Quote context                     |

Optional quote refresh:

```
GET /api/v1/prices/{symbol}
```

## 3. Check Portfolio

```
GET /api/v1/users/{userId}/balance
```

For a plain market buy, check `mUsdBalance`, the API field for `mUSD`. Wallet USDC is not buying power until it is deposited into `mUSD`. If the cash token is approved and instant deposit is available, `/api/v1/orders/with-deposit/calldata` can deposit and place the buy in one transaction.

## 4. Deposit Cash If Needed

First check allowance:

```
GET /api/v1/users/{userId}/balance?spenderAddress={spender}
```

If allowance is too low, have the user approve the spender from [cash/deposits.md](/trading-api/cash-operations/deposits.md).

Then build deposit calldata:

```
POST /api/v1/cash/deposits/calldata
```

Example body:

```json
{
  "userAddress": "0x1111111111111111111111111111111111111111",
  "tokenAddress": "0x2222222222222222222222222222222222222222",
  "tokenAmount": "100"
}
```

Submit the returned `toAddress`, `value`, and `callData` on-chain. Then record:

```
POST /api/v1/cash/deposits/tx
```

Poll deposit detail until `operationStatus` is `settled` or `mUsdBalance` is updated.

## 5. Place a Market Buy

Build order calldata:

```
POST /api/v1/orders/calldata
```

Example body:

```json
{
  "stockAddress": "0x3333333333333333333333333333333333333333",
  "side": "Buy",
  "type": "Market",
  "notional": "10",
  "deadline": 1893456000
}
```

Submit the returned `StockRouter` transaction with your wallet client.

## 6. Record and Track the Order

Record the self-submitted tx:

```
POST /api/v1/orders/tx
```

Example:

```json
{
  "txHash": "0xabc..."
}
```

Then track:

```
GET /api/v1/orders/tx/{txHash}
GET /api/v1/orders/{orderId}
```

The transaction can be mined before execution and settlement are final. Treat the order as final only after it moves into history and portfolio balances reflect the settlement.

## 7. Confirm Portfolio

After settlement:

```
GET /api/v1/users/{userId}/balance
GET /api/v1/users/{userId}/positions
```

Expected result:

* `mUsdBalance` decreases by filled notional plus fees, with unspent `mUSD` refunded.
* The bought stock appears as `exchangeBalance`.
* Order detail shows settlement fields such as `settlePrice`, `settlePay`, and `settleReceive`.

## Next Steps

| Need                | Doc                                                                          |
| ------------------- | ---------------------------------------------------------------------------- |
| viem implementation | [demo-code.md](/trading-api/guides/demo-code.md)                             |
| Debug failures      | [../reference/troubleshooting.md](/trading-api/reference/troubleshooting.md) |
| Understand statuses | [../reference/status-model.md](/trading-api/reference/status-model.md)       |
| Add One Click       | [one-click-flow.md](/trading-api/guides/one-click-flow.md)                   |