🧩Request Payloads & Recipes

Copy-paste request payloads for every Issue & Transfer scenario — issue to self, issue-on-buyer, custom collection, NFC tags, attachments and bulk.

Ready-to-use request bodies for POST <base_url>/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; for failures see Errors & Troubleshooting.

The file URLs in these examples (thumbnailURL, image, contractTerms.fileURL, attachmentFiles[*].url) show the shape of the finalUrl returned by /commerce/signedUrls. Always use that returned value verbatim — it is available immediately in the signed-URL response, before the upload itself.

All requests require the headers commerce-api-key, issuer-address, Content-Type: application/json — see the Issue & Transfer SRR overview.

Body shape

{
  "requestId": "<optional unique UUID>",
  "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.
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.
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.
externalUrls	string[]	optional	Only the first URL is used (becomes metadata.external_url).

Recipes

Minimal (to self)

Issue a single SRR into your own LUW (no to, no collection).

{
  "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"
      }
    }
  ]
}

Issue on buyer

Custom collection

NFC tags

Attachment files

Bulk (mixed)

Rules to remember

• 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 finalUrls returned by /commerce/signedUrls. External URLs are rejected with 400 — see File URLs. (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. Hit an error? → Errors & Troubleshooting.