> 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/flexible-metadata-registered-schemas/registered-schemas/transfers.md).

# Transfers

POST /commerce/srrs/transfers, claim and cancel — transfer by address, reserve by email or reveal hash, locked SRRs, bulk, idempotency, failures.

| Route                                                                                                       | Purpose                                                  |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| <mark style="color:green;">`POST`</mark> `<base_url>/port/api/v1/commerce/srrs/transfers`                   | Transfer or reserve one or more SRRs the issuer LUW owns |
| <mark style="color:green;">`POST`</mark> `<base_url>/port/api/v1/commerce/srrs/{tokenId}/transfers/claim`   | Complete a reservation by revealing the secret           |
| <mark style="color:red;">`DELETE`</mark> `<base_url>/port/api/v1/commerce/srrs/{tokenId}/transfers/pending` | Cancel a pending reservation                             |

Same headers as issuance. The routes are independent of the metadata schema: they work for SRRs on the official schema too.

## Three targets, two on-chain paths

| `to`         | Chain call                                                                | Result                                           | Completed by                                                                                                             |
| ------------ | ------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `address`    | `transferFromWithProvenance`                                              | `mode: transferred` — ownership moves when mined | —                                                                                                                        |
| `email`      | `approveSRRByCommitment` with keccak256 of the trimmed, lower-cased email | `mode: reserved`                                 | The recipient signing in to Startrail with that email, or you via `claim` with `preimage` = the email                    |
| `revealHash` | `approveSRRByCommitment` with your hash                                   | `mode: reserved`                                 | You via `claim` with `revealHash` or `preimage` (the secret whose keccak256 is the hash), or the recipient in the portal |

Exactly one of the three per entry. A reveal hash is accepted with or without `0x`.

{% hint style="warning" %}
**Locked SRRs** (`lockExternalTransfer: true`) cannot be transferred by `address` — the chain would revert, so the request is refused before anything is signed. Reserve them by `email` or `revealHash` instead; reservations work on locked SRRs.
{% endhint %}

## `POST /commerce/srrs/transfers`

| Body field                                                  | Type        | Description                                                                    |
| ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------ |
| `requestId`                                                 | string      | Optional idempotency key, unique per `issuer-address`                          |
| `payload`<mark style="color:red;">\*</mark>                 | array       | 1..n entries; no maximum is enforced                                           |
| `payload[*].tokenId`<mark style="color:red;">\*</mark>      | string      | Token id                                                                       |
| `payload[*].collectionAddress`                              | string      | Required when the SRR lives on a collection                                    |
| `payload[*].externalId`                                     | string      | Your reference, echoed back; not checked for uniqueness                        |
| `payload[*].to`<mark style="color:red;">\*</mark>           | object      | Exactly one of `address`, `email`, `revealHash`                                |
| `payload[*].transferType`<mark style="color:red;">\*</mark> | string      | `Primary sale`, `Secondary sale` or `Other transfer`                           |
| `payload[*].remarks`                                        | object      | Free text per language code, e.g. `{ "en": "…", "ja": "…" }`                   |
| `payload[*].customHistoryId`                                | integer ≥ 1 | Custom history to attach the transfer to; must exist on chain                  |
| `payload[*].isIntermediary`                                 | boolean     | Mark the new owner as an intermediary. `address` targets only. Default `false` |

`transferType`, `remarks` and `customHistoryId` become a transfer-metadata document on the [transfer schema v1.2](https://docs.startrail.io/metadata-schema/transfer/version-1.2.md); its CID is returned per entry and recorded in the provenance.

### Checks before anything is signed

All entries are checked first; one bad entry refuses the whole request.

| Check                                                             | Status |
| ----------------------------------------------------------------- | ------ |
| The same SRR appears once in the payload                          | `400`  |
| Every `customHistoryId` exists on chain                           | `400`  |
| The SRR exists in the subgraph                                    | `404`  |
| The issuer LUW is the current owner                               | `403`  |
| No reservation is pending                                         | `409`  |
| `address` target: SRR not locked, target is not the current owner | `400`  |
| `email` / `revealHash` target: `isIntermediary` not set           | `400`  |
| Transfer metadata valid against the v1.2 schema                   | `400`  |

### Single, bulk, repeated bulk

| Entries                 | Sent as                                                                                                                                                                                                                                                             | `txReceiptId` in the result |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| 1                       | The single startrail-api route                                                                                                                                                                                                                                      | Present                     |
| 2 or more               | One generalized batch (Merkle root over the entries)                                                                                                                                                                                                                | Absent                      |
| 2 or more, **repeated** | The batch root is built from the entries only (token, target, metadata CID, custom history), so the same entries sent again rebuild a root startrail-api already holds and it refuses them. gogh-api then sends the entries **one by one** through the single route | Present, one per entry      |

A repeated bulk is legitimate (reserve, cancel, reserve the same buyer again), which is why it is handled rather than refused. If one entry fails while the rest go out one by one, the entries before it are already sent and cannot be taken back; the error says which — see the [failure table](#failures).

### Response

```json
{
  "results": [
    {
      "externalId": "order-4711",
      "tokenId": "561308332886",
      "collectionAddress": "0x8b116a8896538377328936279e64b11303cbf7b1",
      "mode": "reserved",
      "status": "waiting_for_mining",
      "transferMetadataCID": "bafkreihzvhh7cmetdkjqx557ycvmrlia6aipqqn3hx4pqedspm36ms2k6e",
      "txReceiptId": "12346"
    }
  ],
  "nextStep": "Poll GET /api/v1/srr/{tokenId}: ownerAddress changes (transferred) or transferCommitment is set (reserved). Reserved SRRs complete when the recipient signs in with the email, or through POST /commerce/srrs/{tokenId}/transfers/claim."
}
```

`201` means accepted. A meta-transaction that startrail-api accepts and that reverts on chain afterwards is **not** an HTTP failure: you see it only by polling the SRR (`ownerAddress` or `transferCommitment` unchanged) or through the `transferReservationComplete` / `transferExecutionComplete` [webhooks](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/webhook-setup.md) not arriving. The checks above exist to make that rare.

### Example

```json
{
  "requestId": "transfer-2026-10-27-001",
  "payload": [
    {
      "tokenId": "561308332886",
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "externalId": "order-4711",
      "to": { "email": "buyer@example.com" },
      "transferType": "Primary sale",
      "remarks": { "en": "Sold at the autumn fair" }
    },
    {
      "tokenId": "561308332887",
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "to": { "address": "0xa20B092b5ED1685ab9cdA29507681860Bd976FbD" },
      "transferType": "Secondary sale",
      "isIntermediary": true
    }
  ]
}
```

## `POST /commerce/srrs/{tokenId}/transfers/claim`

Executes a pending reservation to a wallet. The LUW behind the API key must be the SRR's **owner or issuer**; the secret is verified against the on-chain commitment before anything is sent.

| Body field                                     | Type    | Description                                                                                                         |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `requestId`                                    | string  | Optional idempotency key                                                                                            |
| `payload.to`<mark style="color:red;">\*</mark> | string  | Wallet that receives the SRR. Must not be the current owner                                                         |
| `payload.revealHash`                           | string  | The hash the reservation was made with                                                                              |
| `payload.preimage`                             | string  | The secret itself (the email of an email reservation, or your secret). Tried as typed, then trimmed and lower-cased |
| `payload.collectionAddress`                    | string  | Required on a collection                                                                                            |
| `payload.isIntermediary`                       | boolean | Default `false`                                                                                                     |

Exactly one of `revealHash` and `preimage`.

```json
{ "payload": { "preimage": "buyer@example.com", "to": "0xa20B092b5ED1685ab9cdA29507681860Bd976FbD", "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1" } }
```

`201`:

```json
{ "tokenId": "561308332886", "collectionAddress": "0x8b116a8896538377328936279e64b11303cbf7b1", "to": "0xa20B092b5ED1685ab9cdA29507681860Bd976FbD", "status": "waiting_for_mining", "txReceiptId": "12347" }
```

## `DELETE /commerce/srrs/{tokenId}/transfers/pending`

Cancels a reservation that has not been claimed. The SRR stays with the issuer LUW. Direct address transfers cannot be cancelled. No body; the route is not logged for idempotency.

| Query               | Description              |
| ------------------- | ------------------------ |
| `collectionAddress` | Required on a collection |

`200`:

```json
{ "tokenId": "561308332886", "collectionAddress": "0x8b116a8896538377328936279e64b11303cbf7b1", "cancelledCommitment": "0x5c1ae5f8…", "status": "waiting_for_mining", "txReceiptId": "12348" }
```

## Idempotency

| Rule                                                    | Transfer and claim                                                                                                                               | Cancel     |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| Reused `requestId` (per issuer, any earlier status)     | `400` `Duplicate Request Error: Same requestId already logged`                                                                                   | Not logged |
| Identical body while an earlier copy is **in progress** | `400` `Request Content Error: Current request already logged with status in_progress`                                                            | Not logged |
| Identical body after the earlier copy **finished**      | Accepted (unlike issuance and metadata updates) — a repeat can be legitimate, and a harmful one is stopped by the on-chain checks (`403`, `409`) | —          |

There is no time window on either rule.

## Failures

Refused by gogh-api before anything is signed or sent:

| Status | Message                                                                                                                                                          | When                                                                                       |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `401`  | `Missing header` / `API Key is not valid for <issuer-address>`                                                                                                   | Headers                                                                                    |
| `400`  | `payload.<i>.to.address field or one of the following fields (email,revealHash) must not be empty` (and the same for `email`, `revealHash`)                      | `to` has none or more than one of the three                                                |
| `400`  | `payload.<i>.to.address must be a valid Ethereum addresses` / `payload.<i>.to.email must be an email` / `payload.<i>.to.revealHash must be a keccak256 hash`     | Malformed target                                                                           |
| `400`  | `payload.<i>.transferType must be one of the following values: Primary sale, Secondary sale, Other transfer`                                                     | Unknown `transferType`                                                                     |
| `400`  | `payload.<i>.customHistoryId must be an integer number` / `payload.<i>.customHistoryId must not be less than 1`                                                  | Bad `customHistoryId`                                                                      |
| `400`  | `payload must contain at least 1 elements`                                                                                                                       | Empty payload                                                                              |
| `400`  | `tokenId must be a decimal token id (got "<value>")`                                                                                                             | Claim / cancel path param                                                                  |
| `400`  | `Duplicate Request Error: Same requestId already logged`                                                                                                         | `requestId` reused                                                                         |
| `400`  | `Request Content Error: Current request already logged with status in_progress`                                                                                  | Same body still running                                                                    |
| `400`  | `SRR <tokenId> appears more than once in the payload`                                                                                                            | Duplicate token (with `on <collectionAddress>` when on a collection)                       |
| `400`  | `customHistoryId <id> of SRR <tokenId> does not exist on chain`                                                                                                  | Unknown custom history (one sentence per entry, joined by `.` )                            |
| `404`  | `SRR <tokenId> not found`                                                                                                                                        | Not in the subgraph: wrong token, wrong or missing `collectionAddress`, or not indexed yet |
| `403`  | `SRR <tokenId> is owned by <owner>, not by the issuer <issuer-address>`                                                                                          | Transfer, cancel: issuer is not the owner                                                  |
| `403`  | `SRR <tokenId> is neither owned nor issued by <issuer-address>`                                                                                                  | Claim                                                                                      |
| `409`  | `SRR <tokenId> already has a pending transfer; cancel it first (DELETE /commerce/srrs/{tokenId}/transfers/pending)`                                              | Transfer                                                                                   |
| `409`  | `SRR <tokenId> has no pending transfer to claim` / `SRR <tokenId> has no pending transfer to cancel`                                                             | Claim, cancel                                                                              |
| `400`  | `SRR <tokenId> has lockExternalTransfer set; a direct transfer to an address would revert on chain. Transfer it by email or revealHash (commit/reveal) instead.` | Locked SRR, `address` target                                                               |
| `400`  | `SRR <tokenId> is already owned by <address>`                                                                                                                    | Target is the current owner                                                                |
| `400`  | `isIntermediary applies to address transfers only (SRR <tokenId>)`                                                                                               | `isIntermediary` on a reservation                                                          |
| `400`  | `transfer metadata for SRR <tokenId> is invalid. Details: <path> <message>.`                                                                                     | `remarks` or `customHistoryId` break the v1.2 schema                                       |
| `400`  | `payload must contain either preimage or revealHash`                                                                                                             | Claim without a secret                                                                     |
| `400`  | `the preimage does not match the pending transfer of SRR <tokenId>` / `the revealHash does not match the pending transfer of SRR <tokenId>`                      | Wrong secret                                                                               |
| `400`  | `SRR <tokenId> is already owned by <to>; claiming to the current owner would only cancel the reservation`                                                        | Claim addressed to the owner                                                               |
| `4xx`  | `SRR <tokenId> failed: <message>. Already sent and still going to be mined: <tokenId>, <tokenId>`                                                                | A repeated bulk going out one by one failed part-way; the listed entries were sent         |

Returned by startrail-api and passed through with its status and message:

| Status      | Message                                                 | When                                                                                                                                    |
| ----------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | `<message>`                                             | The signing wallet of the API key is not an owner of the LUW; startrail-api's own duplicate-request check; typed-data or nonce problems |
| `404`       | `Custom history with id (<id>) does not exist on chain` | Single transfer with an unknown `customHistoryId` (bulk entries are checked by gogh-api first)                                          |
| `409`       | `<message>`                                             | startrail-api's cache is reloading; retry                                                                                               |
| other `4xx` | `<message>`                                             | As returned                                                                                                                             |

Everything else is `500` `STARTRAIL_ERROR: <reason>` (signing-api failure, transport error, batch construction, subgraph outage during the checks, CID hashing) or the startrail-api 5xx message as it is.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/transfers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
