> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/payloads.md). # Request Payloads & Recipes Ready-to-use request bodies for `POST /port/api/v1/commerce/srrs`. Every example here is **valid against SRR metadata schema v2.2**. For the full field reference and response shapes see [Issue & Transfer](/issue-transfer-api/issue-and-transfer-srr-nft/issue-and-transfer.md); for failures see [Errors & Troubleshooting](/issue-transfer-api/issue-and-transfer-srr-nft/errors.md). {% hint style="info" %} The file URLs in these examples (`thumbnailURL`, `image`, `contractTerms.fileURL`, `attachmentFiles[*].url`) show the shape of the **`finalUrl` returned by** [**`/commerce/signedUrls`**](/issue-transfer-api/issue-and-transfer-srr-nft/request-signed-url-for-upload-download-files.md). Always use that returned value verbatim — it is available immediately in the signed-URL response, before the upload itself. {% endhint %} {% hint style="info" %} All requests require the headers `commerce-api-key`, `issuer-address`, `Content-Type: application/json` — see the [Issue & Transfer SRR overview](/issue-transfer-api/issue-and-transfer-srr-nft.md#required-headers). {% endhint %} ## Body shape ```json { "requestId": "", "payload": [ /* one or more SRR entries */ ] } ``` | Field | Type | Required | Description | | ----------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `requestId` | `string` | optional | Unique idempotency key (UUID recommended). A reused value is rejected — see [idempotency](/issue-transfer-api/issue-and-transfer-srr-nft/errors.md#request-level-errors-400). | | `payload` | `array` | **required** | 1+ SRR entries. Minimum 1; **no hard maximum** (≤ 250 recommended for stable processing). | ### `payload[*]` fields | Field | Type | Required | Description | | ---------------------- | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------ | | `externalId` | `string` | **required** | Your unique reference for this SRR (UUID recommended). Echoed back in the response. | | `metadata` | `object` | **required** | SRR metadata, schema v2.0+. See [SRR metadata v2.2](/metadata-schema/startrail-registry-srr/version-2.2.md). | | `isPrimaryIssuer` | `boolean` | **required** | `true` if you are the primary issuer. | | `lockExternalTransfer` | `boolean` | **required** | `true` to disable standard ERC-721 transfer methods. | | `artistAddress` | `string` (EOA/LUW) | **required** | Artist's Ethereum address. Must be a known LUW. | | `to` | `string` (EOA) | optional | Recipient — SRR is transferred here after minting. Omit to keep it in your LUW. | | `collectionAddress` | `string` | optional | Custom collection contract to mint into (must be owned by `issuer-address`). | | `attachmentFiles` | `array` | optional | Previously uploaded files; folded into metadata server-side. See [recipe](#issue-with-attachment-files). | | `externalUrls` | `string[]` | optional | Only the **first** URL is used (becomes `metadata.external_url`). | ## Recipes {% tabs %} {% tab title="Minimal (to self)" %} Issue a single SRR into your own LUW (no `to`, no collection). ```json { "payload": [ { "externalId": "8f1d4c2a-0e3b-4f7a-9c11-aa0000000001", "isPrimaryIssuer": true, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Sunrise No. 1", "title": { "en": "Sunrise No. 1", "ja": "日の出 No.1" }, "medium": { "en": "Oil on canvas" }, "yearOfCreation": { "en": "2024" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } } ] } ``` {% endtab %} {% tab title="Issue on buyer" %} Set `to` to mint and transfer to a buyer's EOA in one call. ```json { "requestId": "req-2026-06-26-001", "payload": [ { "externalId": "8f1d4c2a-0e3b-4f7a-9c11-aa0000000002", "isPrimaryIssuer": true, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "to": "0x1111111111111111111111111111111111111111", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Blue Composition", "title": { "en": "Blue Composition" }, "medium": { "en": "Acrylic on panel" }, "yearOfCreation": { "en": "2023" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } } ] } ``` {% endtab %} {% tab title="Custom collection" %} Set `collectionAddress` to mint into a [collection](/issue-transfer-api/collection/create-collection.md) you own. ```json { "payload": [ { "externalId": "8f1d4c2a-0e3b-4f7a-9c11-aa0000000003", "isPrimaryIssuer": true, "lockExternalTransfer": true, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "collectionAddress": "0x4412Ba95BEC0CDB4562D97CB9149575Ea5B514A5", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Collection Piece A", "title": { "en": "Collection Piece A" }, "medium": { "en": "Mixed media" }, "yearOfCreation": { "en": "2025" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } } ] } ``` {% endtab %} {% tab title="NFC tags" %} Attach IC tag UIDs. In **v2.2**, `chipUIDs` and `startbahnCertICTagUIDs` are **mutually required** and must hold the **same values**. List multiple UIDs to tag one artwork with multiple chips. ```json { "payload": [ { "externalId": "8f1d4c2a-0e3b-4f7a-9c11-aa0000000004", "isPrimaryIssuer": true, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Tagged Sculpture", "title": { "en": "Tagged Sculpture", "ja": "タグ付き彫刻" }, "medium": { "en": "Bronze" }, "yearOfCreation": { "en": "2022" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "chipUIDs": ["04A1B2C3D4E580", "04F6E7D8C9BA00"], "startbahnCertICTagUIDs": ["04A1B2C3D4E580", "04F6E7D8C9BA00"] } } ] } ``` {% hint style="warning" %} Each IC tag UID consumes one unit of the issuer LUW's NFC-tag allowance. Exceeding it returns `LUW missing NFC tag!` — see [NFC tag errors](/issue-transfer-api/issue-and-transfer-srr-nft/errors.md#nfc-tags-and-quota-errors). {% endhint %} {% endtab %} {% tab title="Attachment files" %} Reference files already uploaded via [`/signedUrls`](/issue-transfer-api/issue-and-transfer-srr-nft/request-signed-url-for-upload-download-files.md). The server resolves each URL, reads its hash, and folds it into `metadata.digitalComponents` (`artwork`) or `metadata.attachmentFiles` (other categories). ```json { "payload": [ { "externalId": "8f1d4c2a-0e3b-4f7a-9c11-aa0000000005", "isPrimaryIssuer": true, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "externalUrls": ["https://gallery.example.com/works/123"], "attachmentFiles": [ { "name": "certificate.pdf", "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/certificate.pdf", "category": "certificate" }, { "name": "hires-artwork.png", "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/hires-artwork.png", "category": "artwork" } ], "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Documented Work", "title": { "en": "Documented Work" }, "medium": { "en": "Photography" }, "yearOfCreation": { "en": "2021" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } } ] } ``` {% hint style="info" %} `category` here accepts `certificate`, `for_authenticity`, `artwork`, `installation`. Wait until the file's hash is computed (poll [`/fileMetadata`](/issue-transfer-api/issue-and-transfer-srr-nft/file-information-metadata.md)) — otherwise issuance returns `Attachment hash not ready …`. {% endhint %} {% hint style="warning" %} The same rule applies to `metadata.thumbnailURL`, `metadata.image` and `metadata.contractTerms.fileURL`: they must be `finalUrl`s from the [signed-URL flow](/issue-transfer-api/issue-and-transfer-srr-nft/request-signed-url-for-upload-download-files.md) (or `ipfs://` URLs) with their `cid` already computed — external hosts are rejected. See [File URLs](/issue-transfer-api/issue-and-transfer-srr-nft/issue-and-transfer.md#file-urls-every-file-must-come-from-the-signed-url-flow). {% endhint %} {% endtab %} {% tab title="Bulk (mixed)" %} One request, multiple SRRs mixing scenarios. Remember: **the batch is atomic** — if any entry fails, none are issued.
Multi-item bulk payload ```json { "requestId": "batch-2026-06-26-A", "payload": [ { "externalId": "bulk-001-self", "isPrimaryIssuer": true, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Batch Piece 1", "title": { "en": "Batch Piece 1" }, "medium": { "en": "Watercolor" }, "yearOfCreation": { "en": "2020" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } }, { "externalId": "bulk-002-to-buyer", "isPrimaryIssuer": false, "lockExternalTransfer": false, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "to": "0x2222222222222222222222222222222222222222", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Batch Piece 2", "title": { "en": "Batch Piece 2", "ja": "バッチ作品2" }, "medium": { "en": "Digital print" }, "yearOfCreation": { "en": "2026" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg" } }, { "externalId": "bulk-003-collection-tags", "isPrimaryIssuer": true, "lockExternalTransfer": true, "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22", "collectionAddress": "0x4412Ba95BEC0CDB4562D97CB9149575Ea5B514A5", "metadata": { "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.2.schema.json", "name": "Batch Piece 3", "title": { "en": "Batch Piece 3" }, "medium": { "en": "Sculpture" }, "yearOfCreation": { "en": "2019" }, "thumbnailURL": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "image": "https://static-files-stg.startrail.startbahn.jp/srr-images/artwork-thumbnail.jpg", "chipUIDs": ["0400112233AABB"], "startbahnCertICTagUIDs": ["0400112233AABB"] } } ] } ```
{% endtab %} {% endtabs %} ## Rules to remember {% hint style="info" %} * **Required metadata fields (v2.2):** `$schema`, `name`, `title`, `thumbnailURL`, `image`, `medium`, `yearOfCreation`. * **All file URLs must come from the signed-URL flow.** `thumbnailURL`, `image`, `contractTerms.fileURL` and `attachmentFiles[*].url` must be the `finalUrl`s returned by [`/commerce/signedUrls`](/issue-transfer-api/issue-and-transfer-srr-nft/request-signed-url-for-upload-download-files.md). External URLs are **rejected with 400** — see [File URLs](/issue-transfer-api/issue-and-transfer-srr-nft/issue-and-transfer.md#file-urls-every-file-must-come-from-the-signed-url-flow). (`external_url` is exempt.) * **Metadata files must be public.** Upload `thumbnailURL` / `image` / `contractTerms.fileURL` files with a **public category** — `non_attachment_file` (recommended) or `artwork`. Private-category files (`certificate`, `for_authenticity`, `installation`) are not accessible to viewers and are rejected for these fields. * **NFC tags:** include `chipUIDs` **and** `startbahnCertICTagUIDs` with identical values. * **Digital works:** if `isDigital: true`, `digitalComponents` is required. * **No hard batch cap**, but keep `payload` ≤ 250 entries for stable processing. * **Atomic batches:** one failed entry cancels the whole request. * Need the response shape and per-field details? → [Issue & Transfer](/issue-transfer-api/issue-and-transfer-srr-nft/issue-and-transfer.md). Hit an error? → [Errors & Troubleshooting](/issue-transfer-api/issue-and-transfer-srr-nft/errors.md). {% endhint %} --- # 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.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/payloads.md?ask=&goal= ``` `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.