# Buy stock

For designers.

Buys batches of a stock for one of its regions, paid from your wallet only: there is no card top-up, so a short balance buys nothing. Auto-reorder spends from the same wallet, so keep enough balance for both.

## What you need

-   `stock_id` (string, required): The stock to buy (`stk_...`).
-   `region_id` (string, required): Where to produce it (`reg_...`), one of the stock regions in `restock[].region.id` of `get_stock`.
-   `batches` (integer, required): How many batches; each holds `units_per_batch` units.
    
    Range at least 1.
    
-   `idempotency_key` (string, required): A unique string for this attempt, for example a UUID. Send the same value when you retry, so the write happens once.

## Step 1: Get a stock

[GET `/v2/stocks/{id}`](https://public-api.dapi.digital/docs/reference/stocks.md#get_stock)

Read the stock. Only an approved stock has a price and regions. A batch costs `batch_price`.

**Parameters**

```json
{
  "path id": "$inputs.stock_id"
}
```

Succeeds when:

-   `$statusCode == 200`
-   `$response.body#/review/status == 'approved'`

Keeps for the next steps:

-   `batch_price`: `$response.body#/batch_price`
-   `units_per_batch`: `$response.body#/units_per_batch`
-   `regions`: `$response.body#/restock`

## Step 2: Get your wallet balance

[GET `/v2/wallet`](https://public-api.dapi.digital/docs/reference/wallet.md#get_wallet)

Read the wallet. The purchase needs `batch_price` times `batches` in `balance`; top up in the dashboard when it is short.

Succeeds when:

-   `$statusCode == 200`

Keeps for the next steps:

-   `balance`: `$response.body#/balance`

## Step 3: Buy stock batches

[POST `/v2/stock-purchases`](https://public-api.dapi.digital/docs/reference/stocks.md#create_stock_purchase)

Buy. `insufficient_balance` (402) comes with `details.required` and `details.balance`; nothing was bought. `region_not_available` (422) means the region is not one of the stock regions.

**Parameters**

```json
{
  "header Idempotency-Key": "$inputs.idempotency_key"
}
```

**Request body**

```json
{
  "items": [
    {
      "stock": "$inputs.stock_id",
      "region": "$inputs.region_id",
      "batches": "$inputs.batches"
    }
  ]
}
```

Succeeds when:

-   `$statusCode == 201`

Otherwise:

-   `retry_server_error`: retry after 5 seconds, at most 3 times, when `$statusCode >= 500`.
-   `insufficient_balance`: stop the workflow when `$statusCode == 402`.
-   `region_not_available`: stop the workflow when `$statusCode == 422`.

Keeps for the next steps:

-   `purchase_reference`: `$response.body#/purchase_reference`
-   `total`: `$response.body#/total`
-   `batches`: `$response.body#/batches`

## As a workflow file

The workflow returns:

-   `purchase_reference`: `$steps.purchase.outputs.purchase_reference`
-   `total`: `$steps.purchase.outputs.total`

Values starting with `$` are filled in as you go: `$inputs.x` is something you provide, `$steps.s.outputs.o` is a value an earlier step returned, and `$response.body#/path` a field of this response.

This recipe is the workflow `buy_stock` of [arazzo.json](https://public-api.dapi.digital/docs/arazzo.json), an [Arazzo 1.0](https://spec.openapis.org/arazzo/latest.html) document that tools and AI agents can follow step by step.

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/guides/buy-stock. Index of every page: https://public-api.dapi.digital/docs/llms.txt.