> For the complete documentation index, see [llms.txt](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/api/rwa.md).

# RWA

REST API for querying Real-World Assets, managing NFTs, and triggering on-chain mints.

**Base URL:** `https://rwa.onchainlabs.ch` \
**Prefix:** `/v1/api/` \
**Format:** JSON

### Authentication

Required header:

```
x-api-key: <your_api_key>
```

The key is validated against the WalletTwo auth service and all queries are automatically scoped to the associated company.

**Common errors:**

* `401 x-api-key header missing.` — Header missing
* `401 Invalid API key.` — Key does not exist or has been revoked

***

### Endpoints

#### 1. List RWAs

**GET** `/v1/api/rwa`

| Param         | Type    | Default | Notes                   |
| ------------- | ------- | ------- | ----------------------- |
| `type`        | string  | —       | Filter by RWA type      |
| `isBuyable`   | boolean | —       | Only Stripe-purchasable |
| `isClaimable` | boolean | —       | Only on-chain claimable |
| `limit`       | integer | 50      | Max 200                 |
| `offset`      | integer | 0       | Pagination              |

**Response 200:** `{ total, limit, offset, rwas: [...] }`

***

#### 2. RWA Detail

**GET** `/v1/api/rwa/{id}`

**Response 200:** Full RWA object with `totalNfts`, `claimedNfts`, `unclaimedNfts` and nested `data`.

**Error 404:** RWA does not exist or belongs to another company.

***

#### 3. List NFTs of an RWA

**GET** `/v1/api/rwa/{id}/nfts`

| Param     | Type    | Notes                          |
| --------- | ------- | ------------------------------ |
| `claimed` | boolean | true = minted; false = pending |
| `limit`   | integer | Default 50, max 200            |
| `offset`  | integer | Default 0                      |

**Response 200:** Array of NFTs with `secret`, `url` and claim status.

***

#### 4. Issue new NFTs (batch, no mint)

**POST** `/v1/api/rwa/{id}/nfts`

```json
{ "count": 10 }
```

`count` between 1 and 100. Creates the NFTs in DB but does **not** mint them on-chain.

**Response 200:** `{ created, nfts: [...] }` with auto-generated `serial` and `secret`.

***

#### 5. Create and mint an RWA NFT *(new)*

**POST** `/v1/api/rwa/{id}/mint`

Creates a new NFT for the given RWA and queues it for on-chain minting in a single call.

**Body:**

```json
{
  "wallet": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
```

**Validations:**

* The RWA must belong to the API key's company
* The RWA must have `isClaimable: true`
* The RWA's `chainId` must be supported

**Response 200:**

```json
{
  "message": "NFT created and queued for minting",
  "nft": { "id": "...", "serial": "...", "secret": "...", "rwaId": "..." }
}
```

Confirms it was queued — not completed. Poll `GET /v1/api/nft/{id}` to check status.

***

#### 6. List company NFTs

**GET** `/v1/api/nft`

| Param     | Type    | Notes                          |
| --------- | ------- | ------------------------------ |
| `rwaId`   | UUID    | Filter by RWA                  |
| `claimed` | boolean | true = minted; false = pending |
| `limit`   | integer | Default 50, max 200            |
| `offset`  | integer | Default 0                      |

**Response 200:** Array of NFTs across all company RWAs, with nested `rwa` object.

***

#### 7. NFT Detail

**GET** `/v1/api/nft/{id}`

**Response 200:** NFT object with full RWA info and NFT-specific data.

**Errors:**

* 404 — NFT does not exist
* 403 — NFT belongs to another company

***

#### 8. Mint an existing NFT *(updated)*

**POST** `/v1/api/nft/{id}/mint`

Replaces the old `POST /v1/api/nft/claim`. The NFT is referenced by URL — `ids` are no longer sent in the body.

**Body:**

```json
{
  "secret": "a1b2c3...",
  "wallet": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
```

**Validations:**

* `secret` must match the NFT's secret
* The NFT must belong to the API key's company
* `mintedAt` must be `null` (not yet claimed)
* The RWA must have `isClaimable: true`
* The `chainId` must be supported

**Response 200:**

```json
{
  "message": "NFT queued for minting",
  "nft": { "id": "...", "serial": "...", "rwaId": "...", "mintedAt": null }
}
```

Confirms queued — not completed. Poll `GET /v1/api/nft/{id}` to see `mintedTx` / `mintedBlock` when finished.

**Errors:**

* 400 — Missing or invalid fields
* 403 — NFT belongs to another company
* 404 — NFT does not exist