> 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)                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.anchored.finance/trading-api/guides/quickstart-first-trade.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.