# AIOZ Pin — NFT

Base URL: https://api.aiozpin.network/api
Authentication: pinning_api_key + pinning_secret_key headers

## Setup

```typescript
const BASE = 'https://api.aiozpin.network/api'
const PIN_HEADERS = {
  'pinning_api_key': process.env.AIOZ_PIN_API_KEY!,
  'pinning_secret_key': process.env.AIOZ_PIN_SECRET_KEY!
}
```

---

## Create NFT

POST https://api.aiozpin.network/api/nft/

Upload an asset file and a metadata JSON file together. Both are pinned to IPFS and linked as an NFT record.

Metadata JSON format:
```json
{
  "name": "My Awesome NFT",
  "description": "Description of the NFT",
  "properties": [
    { "trait_type": "Color", "value": "Red" },
    { "trait_type": "Rarity", "value": "Medium" }
  ]
}
```

```typescript
import fs from 'fs'
import FormData from 'form-data'

async function createNft(assetFilePath: string, metadataFilePath: string) {
  const form = new FormData()
  form.append('file', fs.createReadStream(assetFilePath))
  form.append('metadata', fs.createReadStream(metadataFilePath))

  const res = await fetch(`${BASE}/nft/`, {
    method: 'POST',
    headers: { ...PIN_HEADERS, ...form.getHeaders() },
    body: form
  })
  return res.json()
}

const result = await createNft('./asset.png', './metadata.json')
// result.data.id
// result.data.asset_cid     — CID of the asset file
// result.data.metadata_cid  — CID of the metadata JSON
// result.data.asset_pin_id
// result.data.metadata_pin_id
// result.data.size
// result.data.pinned
// result.data.status
```

Response fields:
- id, asset_cid, metadata_cid, asset_pin_id, metadata_pin_id
- size, user_id, created_at, updated_at, pinned
- metadata_asset: { name, type }
- status

Optional query param: `?cid={existing_asset_cid}` to use a pre-pinned asset CID.

---

## Get NFT by ID

GET https://api.aiozpin.network/api/nft/{nftId}

```typescript
async function getNft(nftId: string) {
  const res = await fetch(`${BASE}/nft/${nftId}`, { headers: PIN_HEADERS })
  return res.json()
}

const result = await getNft('f0cda369-2846-414d-8e8d-8c0394113bef')
// result.data.asset_cid
// result.data.metadata_cid
// result.data.pinned
```

---

## List NFTs

GET https://api.aiozpin.network/api/nft/nfts/

```typescript
async function listNfts(options: {
  offset?: number
  limit?: number
  pinned?: 'all' | 'true' | 'false'
  sortBy?: 'created_at' | 'size' | 'name'
  sortOrder?: 'ASC' | 'DESC'
} = {}) {
  const { offset = 0, limit = 10, pinned = 'all', sortBy = 'created_at', sortOrder = 'DESC' } = options
  const params = new URLSearchParams({
    offset: String(offset),
    limit: String(limit),
    pinned,
    sortBy,
    sortOrder
  })
  const res = await fetch(`${BASE}/nft/nfts/?${params}`, { headers: PIN_HEADERS })
  return res.json()
}

const result = await listNfts({ pinned: 'true' })
// result.data.totals.files
// result.data.totals.size
// result.data.nfts[]  — array of NFT objects with asset_cid, metadata_cid, etc.
```