Startrail APIs
  • 🛫Startrail PORT: All in one document for API/SDK
    • 🔀URL per environment
  • Issue transfer api
    • 📬Issue & Transfer SRR (NFT)
      • Request Signed URL for Upload/Download Files
      • File Information Metadata
      • Issue & Transfer
      • Webhook Setup
    • 📂Collection
      • Create Collection
      • Get Collection of LUW
    • 📢Change Logs
      • v1.2.0
      • v1.1.0
      • v1.0.1
  • Metadata Schema
    • 🪅Startrail Registry (SRR)
      • Version 2.2
      • Version 2.1
      • Version 2.0
    • 📤Transfer
      • Version 1.2
      • Version 1.1
      • Version 1.0
    • ☸️Custom History
      • Custom History of Exhibition
        • Version 1.2
      • Custom History of Auction
        • Version 1.3
      • Custom History of Appraisal
        • Version 1.1
      • Custom History of Restoration
        • Version 1.0
      • Custom History of Offchain
        • Version 1.1
  • Get SRR API
    • Get Owned SRRs
    • Get SRR by Collection contract address and Token Id
      • 🚫Get SRR by Token Id
    • Description Of SRR Data
  • Ethereum Signature Validator API
    • 🔏Ethereum Signature Validator API
      • Change Logs
  • Startrail SDK Js
    • 🔰Introduction
    • 🏃Getting Started
      • RPC endpoint and chainId
    • 💳Wallet Methods
    • 🔮Startrail API Methods
      • Add Custom Histories To SRRs
      • Approve SRR By Commitment
      • Bulk
      • Check ERC2981 Royalty
      • Create Collection
      • Convert Metadata
      • Create SRR
      • Transfer Collection Ownership
      • Transfer SRR To Ethereum Address
      • Transfer From With Provenance
      • Update Metadata
    • 📱Login Providers
      • Interface
      • Whitelabeling/Customizing
        • Email Password
      • Hints
      • Multi Factor Account Management
    • 🦊MetaMask
    • 🎎Authentication Integration
    • 👾Errors
    • 📢Change logs
      • v1.35.0
      • v1.34.0
      • v1.33.2
      • v1.33.1
      • v1.32.0
      • v1.31.1
      • v1.30.6
      • v1.30.5
      • v1.30.4
      • v1.30.3
      • v1.30.2
      • v1.30.1
      • v1.30.0
      • v1.29.1
      • v1.29.0
      • v1.28.2
      • v1.28.1
      • v1.28.0
      • v1.27.1
      • v1.27.0
      • v1.26.0
      • v1.25.2(Security Patch)
  • Startrail API
    • 💱Transfer SRR Ownership By RevealHash
    • Get Transaction Data
    • Get Metadata By tokenid
  • Subgraph
    • 📊A introduction of subgraph
    • How to retrieve SRR metadata
Powered by GitBook

©2023 Startbahn, Inc.

On this page
  • Precaution
  • Swagger Endpoint (Test Environment)
  • Required Permissions
  • Request Body Example
  • Code Example

Was this helpful?

  1. Issue transfer api
  2. Issue & Transfer SRR (NFT)

Issue & Transfer

to issue or issue+transfer SRR

PreviousFile Information MetadataNextWebhook Setup

Last updated 7 months ago

Was this helpful?

POST <base_url>/port/api/v1/commerce/srrs

Please replace <base_url> as explained .

Precaution

Multiple issuance

Feel free to include more than one issuance in a single request via the payload array. The minimum number of issue requests is one. Though there is no fixed upper limit for the number of issue requests you can submit at one time, we recommend limiting batches to no more than 250 issue requests for optimal processing.

issue to issuer

If payload[*].to is not given, your SRR will be issued to your luw address

Headers

Name
Type
Description

commerce-api-key*

string

Commerce API Key

issuer-address*

string

Contract Address of API Key owner

Request Body

Name
Type
Description

requestId

string

A requestId given by the caller, to ensure requests are only processed once. If the requestId is known and processed before, api will not process this call again, and respond with an error. A good practice is using random UUID.

*requestId must be unique for a given issuer-address. As a result any duplicate combination of requestId and issuer-address is instantly rejected with no impact on either.

payload*

array

payload[*].externalId*

string

An ID to identify the record in your system. We recommend to use UUID, but it can use any string as long it is unique in your system.

payload[*].metadata*

object

The API accepts versions 2.0 and higher.

payload[*].artistAddress*

string

The ethereum address of the artist of the artwork.

payload[*].isPrimaryIssuer*

boolean

If you are the primary issuer of this NFT, set this to true.

payload[*].lockExternalTransfer*

boolean

If you want to prevent your NFTs to be transferred on decentralized marketplaces, set this to true.

payload[*].to

string

Ethereum address target the NFT should be sent to after minting (Issue on Buyer).

If none is given the NFT will be minted into your LUW by default.

payload[*].attachmentFiles

Array<object>

Attachment files that will be included in SRR.

payload[*].attachmentFiles[*].name

string

The name of file.

This is used for when the file is downloaded or shown. The extension is recommended to be the same as the actual uploaded file.

payload[*].attachmentFiles[*].category

string

Please note that contract terms and thumbnail are NOT attachment files. The URL for contract terms and thumbnail are needed for metadata. (See metadata attribute)

payload[*].attachmentFiles[*].url

string

payload[*].collectionAddress

string

The address of collection that the SRR will belong to. This collection must be owned by the caller issuer-address.

The API responds with 201. see Response Body results[*].status for details of each entry.

Body Attribute
Description
Format

results

results of the request

Array

results[*].srr

Detail of the SRR. Please check example for detailed information.

object

results[*].externalId

ID to identify the SRR. Defined by client when calling.

string

results[*].status

string

After a successful issuance, 2 types of JSONs will be returned in results[*].srr.metadata:

  1. json

    It is converted from the originalJson. The object contains some values that are different from those that are written on chain. This json is meant to be easier for consumption on third party applications and it is maintained for backward compatibility. For example if an ipfs link exists in the metadata, this json converts it to an https link for easier consumption.

  2. originalJson

    It is equal to what is written on chain. So if you want to consume this field, some carings are needed. For example it can contain ipfs links like ipfs:// that requires conversion before a browser can display it.

* both of the above JSONs may be different from what originally sent in the request payload.

{
  "results": [
    {
      "status": "waiting_for_mining",
      "srr": {
        "tokenId": "149941159501",
        "collectionContractAddress": "0x552e100d1c368435db99974C658c757E8A6102Dd",
          "collection": {
            "contractAddress": "0x552e100d1c368435db99974C658c757E8A6102Dd",
            "name": "Test",
            "symbol": "TTT"
        },
        "artist": {
          "contractAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22",
          "originalName": "artist orignal name",
          "englishName": "artist english name",
          "userType": "artist",
          "createdAt": "2022-04-14T03:15:35.153Z",
          "updatedAt": "2022-04-14T03:15:35.153Z"
        },
        "issuer": {
          "contractAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22",
          "originalName": "artist orignal name",
          "englishName": "artist english name",
          "userType": "artist",
          "createdAt": "2022-04-14T03:15:35.153Z",
          "updatedAt": "2022-04-14T03:15:35.153Z"
        },
        "isPrimaryIssuer": true,
        "issuedAt": "2022-04-14T03:15:35.153Z",
        "metadata": { 
          "json": {
            // converted verion of originalJson. It converts some fields from the originalJson
            // for backward compatibility and easier consumption reasons
            //   This JSON may be different from the one sent in the request payload, 
            //   because Startbahn update it to comply with the latest version
          },
          "originalJson": {
            // The JSON that is saved on chain.
            //   This JSON may be different from the one sent in the request payload, 
            //   because Startbahn update it to comply with the latest version
          },
          "digest": "b764ad28dec64764c83089967db4710c94d831c677424d1883....",
        },
        "createdAt": "2022-04-14T03:15:35.153Z",
        "updatedAt": "2022-04-14T03:15:35.153Z"
      },
      "externalId": "c0456840-5bdf-4375-a6ce-106697b7dfb7"
    }
  ]
}

The API responds with 400 if request body invalid or some validation errors that can be instantly detected.

// If the metadata is same with another previous SRR
{
  "statusCode": 400,
  "message": {
    "results": [
      {
        "status": "failed",
        "externalId": "c0456840-5bdf-4375-a6ce-106697b7dfb7",
        "message": "DUPLICATE_METADATA"
      }
    ]
  }
}

{
  "statusCode": 400,
  "message": {
    "results": [
      {
        "status": "failed",
        "externalId": "c0456840-5bdf-4375-a6ce-106697b7dfb7",
        "message": "DUPLICATE_CHIP"
      }
    ]
  }
}


{
    "statusCode": 400,
    "message": "Request Content Error: Current request already logged with status successful"
}


{
    "statusCode": 400,
    "message": {
        "results": [
            {
                "status": "failed",
                "externalId": "bulk20122fdredcd2dfve",
                "message": "UNKNOWN_ERROR: external ID: bulk20122fdredcd2dfve."
            }
        ]
    }
}

{
  "statusCode": 400,
  "message": {
    "results": [
      {
        "status": "failed",
        "externalId": "c0456840-5bdf-4375-a6ce-106697b7dfb7",
        "message": "UNKNOWN_ARTIST"
      }
    ]
  }
}

// If metadata with issuer and artist combination is already sent
{
  "statusCode": 400,
  "message": "Request Content Error: Current request already logged with status successful"
}

// DTO validation error
{
    "statusCode": 400,
    "message": [
        "payload.0.metadata is invalid. Check it against the metadata JSON schema. Details:  should have required property 'title' ({\"missingProperty\":\"title\"}).",
        "payload.0.artistAddress must be a valid Ethereum addresses",
        "payload.0.externalId should not be empty",
        "payload.0.externalId must be a string"
    ]
}

Multiple issuance

In case of multiple/bulk issuance as soon as one case failed, the rest of the payload will be definitely failed as well.

Example of duplicated metadata

{
    "statusCode": 400,
    "message": {
        "results": [
            {
                "status": "failed",
                "externalId": "anId",
                "message": "DUPLICATE_METADATA"
            },
            {
                "status": "failed",
                "externalId": "anId",
                "message": "SRR_NOT_CREATED: Not created because there is SRR in the same batch that error"
            }
        ]
    }
}

Example of DTO validation error

{
    "statusCode": 400,
    "message": [
        "payload.1.metadata is invalid. Check it against the metadata JSON schema. Details:  should have required property 'title' ({\"missingProperty\":\"title\"}).",
        "payload.1.artistAddress must be a valid Ethereum addresses",
        "payload.1.externalId should not be empty",
        "payload.1.externalId must be a string"
    ]
}

The API responds with 5xx if there are other issues, such as deeper validation errors.

// For example in case of collection ownership issue
{
  "statusCode": 500,
  "message": "STARTRAIL_ERROR: <reason>"
}

// In case there is unknown error. Please contact us.
{
  "statusCode": 500,
  "message": "UNKNOWN_ERROR: external ID: xxxx"
}

Swagger Endpoint (Test Environment)

Required Permissions

Request Body Example

{
  "requestId": "0004f572-7769-4b8b-8108-a13a36cd88d4",
  "payload": [
    {
      "externalId": "0004f572-7769-4b8b-8108-a13a36cd88d4",
      "metadata": {
        "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.1.schema.json",
        "$schemaIntegrity": "sha256-15f8e99eb9d4292287282942db2f2de9bbcc4761c555c6f7da23feec010c1221",
        "title": {
          "en": "A title",
          "ja": "タイトル",
          "zh": "一个标题"
        },
        "size": {
          "width": 200,
          "height": 400,
          "depth": 12.4,
          "unit": "pixel",
          "flexibleDescription": {
            "en": "flexibleDescription comes here",
            "ja": "自由だーーー"
          }
        },
        "medium": {
          "en": "Oil on canvas",
          "ja": "キャンバスに油彩",
          "zh": "布面油画"
        },
        "edition": {
          "uniqueness": "unique work",
          "proofType": "ED",
          "number": 1,
          "totalNumber": 3,
          "note": {
            "en": "some extra notes in 1 or more languages"
          }
        },
        "contractTerms": {
          "royaltyRate": 15.7,
          "fileURL": "https://startrail.io/whitepaper/startrail_wp_en_v1.1.pdf"
        },
        "note": {
          "en": "note",
          "zh": "注意"
        },
        "thumbnailURL": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "yearOfCreation": {
          "en": "around 2010-2020",
          "ja": "2010年から2020年頃"
        },
        "isDigital": true,
        "name": "some nft name",
        "description": "some nft description",
        "image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "external_url": "https://openseacreatures.io/3"
      },
      "artistAddress": "0x36E9f4C26357FDb14AdF939a12AdBba92a209C01",
      "isPrimaryIssuer": true,
      "lockExternalTransfer": false,
      "to": "0x36E9f4C26357FDb14AdF939a12AdBba92a209C01",
      "collectionAddress": "0xfbF4C1A1eb4258aE0F74807f6c1e854918DC8ed3",
      "attachmentFiles": [
        {
          "name": "image-example.jpg",
          "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/image-example.jpg",
          "category": "artwork"
        },
        {
          "name": "certificate-example.jpg",
          "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/certificate-example.jpg",
          "category": "certificate"
        },
        {
          "name": "for_authenticity.jpg",
          "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/for_authenticity.jpg",
          "category": "for_authenticity"
        },
        {
          "name": "installation.jpg",
          "url": "https://static-files-stg.startrail.startbahn.jp/srr-images/installation.jpg",
          "category": "installation"
        }
      ]
    }
  ]
}

Code Example

If you have a TAG for a physical artwork please add

chipUIDs and startbahnCertICTagUIDs both at the same time and they both need to contain the same value. The value is an array containing the list of the Chip UIDs. For example

"startbahnCertICTagUIDs": [
    "1234567890abcdef"
],
"chipUIDs": [
    "1234567890abcdef"
],

Array of issue requests. Further constraints explained .

The metadata to be issued as a complex object. Detailed schema specification can be found .

Please refer to to understand the difference among the categories.

For the time being, the URL must be under Startbahn's GCS bucket. This can include finalUrl's that is the field in the response of the or a URL that has already been prepared for the client by Startbahn's team. Any other URL will result to rejecting the request without issuing the SRR

waiting_for_miningwait for completion of blockchain mining. The status can be confirmed via or less favorably via REST endpoint.

Check the .

Check .

📬
here
Swagger to test
parent page
parent page
here
this page
singed URL endpoint
subgraph
this
above