> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/chi/tools/oneitem.md).

# ONEitem Developer Guide

This guide is for game developers integrating with ONE store ONEitem. Blue arrows in the diagrams and ● marks in the flow tables indicate what the game developer implements.

**Updated** 2026-11-03 · **SDK version** 2.2.0 · **Supported** Korea · Android

{% hint style="info" %}
**Developers onboarding to ONEitem must** [**comply with the ONEitem policies**](https://onestore-dev.gitbook.io/dev/oneitem/guide)**.** Please review the guide before starting your integration. ONEitem is currently operating as a Closed Beta and will officially launch in ONEconsole. The service is available in Korea, and support for other countries will expand over time. \
\
During the Closed Beta, onboarding is open to developers who have individually agreed with ONE store. If you would like to join, please contact us through Contact Us in ONEconsole.

[Go to the ONEitem introduction](https://m.onestore.co.kr/images/event/EVENT_261016877/preview/main.html)
{% endhint %}

## 1. Overview

By implementing the 8 APIs below on your game server, you can offer account linking, inventory lookup, sale listing, delivery of purchased items, and sale cancellation through ONEitem. All APIs are server-to-server (S2S) calls in which **the ONEitem server calls your game server**. Never put the authentication key in the game client or a WebView.

<table data-search="false"><thead><tr><th width="202">Function</th><th>Method and path</th><th>When it is called</th></tr></thead><tbody><tr><td>Maintenance check</td><td><code>GET /v1/status</code></td><td>Before a trade, to check whether the game is under maintenance</td></tr><tr><td>Inventory lookup</td><td><code>GET /v1/inventory</code></td><td>When a seller picks items to sell</td></tr><tr><td>Recipient validation</td><td><code>POST /v1/recipients/validations</code></td><td>When a buyer enters the account to receive the item</td></tr><tr><td>Sale quantity lock</td><td><code>POST /v1/locks</code></td><td>When a sale is listed</td></tr><tr><td>Item transfer</td><td><code>POST /v1/transfers</code></td><td>After the purchase payment completes</td></tr><tr><td>Unlock</td><td><code>POST /v1/unlocks</code></td><td>When a sale is cancelled or a trade is confirmed as failed</td></tr><tr><td>Operation result lookup</td><td><code>GET /v1/operations</code></td><td>To check the result after a lost response or timeout</td></tr><tr><td>Link token exchange</td><td><code>POST /v1/link-tokens/exchanges</code></td><td>When a member links a game account to ONEitem</td></tr></tbody></table>

Payment, sale proceeds, and settlement are outside the scope of this integration.

## 2. Before You Start

Complete the onboarding application, game and item registration, and your game-side policy decisions before starting development.

#### 2.1 Onboarding Process

1. Sign up for the ONE store Developer Center (ONEconsole). To receive fee settlements, register as a Paid Developer.
2. During the Closed Beta, you can start the integration after contacting us about onboarding through Contact Us in ONEconsole.
3. You can proceed after signing the ONEitem onboarding agreement.

#### 2.2 Review Criteria

<table><thead><tr><th width="235">Item</th><th>Criteria</th></tr></thead><tbody><tr><td>Game type</td><td>No web-board (Go-Stop, poker-type), betting, odds, or casino elements</td></tr><tr><td>Game terms of service</td><td>Must include a clause allowing secondary trading of items through ONE store (if missing, a revision schedule must be confirmed)</td></tr><tr><td>Traded items</td><td>Sample check that registered items are obtained only through paid purchase</td></tr><tr><td>Integration verification</td><td>Pass API verification in the test environment (including timeout and duplicate-call handling)</td></tr></tbody></table>

#### 2.3 Game Information

<table><thead><tr><th width="205">Item</th><th width="151">Required</th><th>Details</th></tr></thead><tbody><tr><td>Game name</td><td>Required</td><td>Multiple languages supported</td></tr><tr><td>Icon</td><td>Required</td><td>512×512, jpg·png</td></tr><tr><td>Graphic image</td><td>Required</td><td>1024×578</td></tr><tr><td>Store identifier</td><td>At least 1</td><td>ONE store PID, Google Play package name, Apple app ID, Windows·Web URL</td></tr></tbody></table>

Games already on ONE store reuse their existing product information. For other games, enter the information directly in the console and a ONEitem game ID is issued. Use this game ID in the SDK `setGameId()`.

#### 2.4 Item Catalog Registration

Only items registered in the catalog can be sold. An item that appears in the inventory lookup but is not in the catalog is shown as not for sale.

<table data-search="false"><thead><tr><th>Item</th><th width="130">Required</th><th>Details</th></tr></thead><tbody><tr><td>Item ID</td><td>Required</td><td>Unique value defined by the developer. Same value as <code>developer_item_id</code> in the inventory lookup response</td></tr><tr><td>Item name · description</td><td>Required</td><td>Korean</td></tr><tr><td>Icon</td><td>Optional</td><td>Displayed as a square on screen</td></tr><tr><td>Category</td><td>Optional</td><td>Multiple values allowed</td></tr><tr><td>Origin server</td><td>Required</td><td>Server the item belongs to</td></tr><tr><td>Transferable servers</td><td>Optional</td><td>If not set, trading is limited to the origin server</td></tr><tr><td>Item acquisition type</td><td>Required</td><td>Classification by how the item is obtained (see 2.5)</td></tr><tr><td>Distribution region</td><td>Optional</td><td>Republic of Korea</td></tr></tbody></table>

* Once an item is on sale, it cannot be deleted; it can only be set to sale-suspended.
* The registration method (console entry or server integration) and update frequency will be provided during onboarding.

#### 2.5 Tradable Item Criteria&#x20;

**Only tradable items can be selected. You must refer to “1. Tradable Items” in the** [**ONEitem Compliance Policy.**](https://onestore-dev.gitbook.io/dev/oneitem/guide)

**① Direct Purchase:** Can be traded if the user paid for and directly purchased a specific item or a package with fixed contents. However, items whose options are randomly determined at purchase cannot be traded.

**② User-to-User Purchase:** Can be traded if the system can confirm that the item was first obtained through a permitted type such as ①, ③, or ④. Items that were enhanced by chance after purchase, items whose original acquisition path cannot be identified, and items obtained by abnormal means cannot be traded.

**③ Paid Random Box (Unopened):** Can be traded if the random box was purchased by the user with payment and the system can confirm it is unopened. However, random boxes or items given for free as bonuses or gifts with a paid purchase are treated as ⑥ Free Random Box, even if related to a paid purchase, and cannot be traded.

**④ Gameplay Reward (Guaranteed):** Items given with certainty through gameplay, without any element of chance, can be traded.

#### 2.6 Decisions for the Developer

<table data-search="false"><thead><tr><th width="201">Item</th><th>Details</th><th>Related</th></tr></thead><tbody><tr><td>Game account ID</td><td>An internal ID with no meaning outside the game. Email, nickname, or real name must not be used. Max 128 characters</td><td><code>game_account_id</code>, <code>setGameUserId()</code></td></tr><tr><td>Server ID scheme</td><td>Game server identifier. Determined by <code>server_id</code> in the link token exchange result; SDK <code>setServerName()</code> is for display only. Games without servers use an empty string</td><td><code>server_id</code></td></tr><tr><td>Recipient input fields</td><td>Fields that identify the account receiving the item (e.g., account ID, character name)</td><td><code>recipient</code></td></tr><tr><td>Link token issuing path</td><td>Existing login-session path from game client to game server</td><td>4.1 Account Linking</td></tr><tr><td>Developer country</td><td>For overseas developers, <code>setDeveloperOverseas(true)</code>. Members are additionally asked to consent to cross-border transfer of personal data; ONE store handles the consent screen</td><td>SDK <code>ONEitemParams</code></td></tr><tr><td>Locked item handling</td><td>Prevent quantities locked by a sale listing from being used, moved, or traded in the game, and show their status on screen</td><td><code>POST /v1/locks</code></td></tr><tr><td>Operational info</td><td>Base URL, authentication key, firewall, maintenance policy, incident contact</td><td>Confirmed during onboarding</td></tr></tbody></table>

#### 2.7 Service Policies

* **Account linking**: Per game, one ONE store member can be linked to only one game account. Linking cannot be removed while items are on sale.
* **Member eligibility**: Only ID members aged 19 or older can trade. Members logged in with a mobile phone number and minors cannot link accounts. ONE store determines eligibility and does not pass it to the developer.
* **Trading method**: Fixed-price sales only. The sale period is 30 days; when it expires, the lock is released and the items return to the seller.
* **Fees**: Platform fee 15%, developer fee 15%. The settlement cycle and method will be provided separately.
* **Operational responsibility**: The developer responds to abnormal-item notifications and trade dispute inquiries. If the developer is at fault (non-delivery, rollback, service termination, etc.), the buyer is refunded.

## 3. Integration Setup

#### 3.1 Connection Information

Provide ONEitem with a **base URL** (`https://<game-server-host>`) and an **authentication key** per game. ONEitem uses these two values to identify the target game.

* All API paths are under `/v1`.
* No game ID is included in paths, bodies, or headers.
* If one server hosts multiple games, issue a different base URL or authentication key per game. Do not use the same URL and key combination for multiple games.
* Firewall allowlist IPs for ONEitem → game server are agreed separately.

#### 3.2 Authentication and Common Headers

Production uses HTTPS only. Receive the key you issued in the `X-API-Key` header. The key must be **at least 32 bytes** with no leading or trailing whitespace or line breaks.

```
X-API-Key: <key issued by the developer>
Accept: application/json
Content-Type: application/json
```

#### 3.3 Common Rules

| Item                    | Rule                                                                 |
| ----------------------- | -------------------------------------------------------------------- |
| Request·response format | JSON. Do not add wrappers such as `data`                             |
| Successful response     | Only HTTP 200 is treated as success. 201, 202, and redirects are not |
| Request timeout         | 5 seconds (current setting on the ONEitem caller side)               |
| Response body size      | Max 1 MiB                                                            |
| Undefined fields        | No model allows properties other than those specified                |

#### 3.4 Key Identifiers

| Field             | Meaning                                                                                             | Format·constraints                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `server_id`       | Game server identifier                                                                              | String, 1–128 characters                                                                                    |
| `game_account_id` | Game account identifier (separate from the ONE store member ID)                                     | String, 1–128 characters                                                                                    |
| `inventory_ref`   | Identifier of an item held by an account (separate from the item definition ID `developer_item_id`) | String, 1–128 characters                                                                                    |
| `quantity`        | Quantity                                                                                            | Positive integer **string**, 1–9223372036854775807. `"3"` is valid; `3`, `"03"`, `"0"`, `"1.5"` are invalid |
| `operation_key`   | Operation key created by ONEitem. Does not change on retry                                          | String, 1–256 characters, may include `/`                                                                   |
| `generation`      | Lock generation fixed by ONEitem (not a retry count)                                                | Integer, 1–4294967295                                                                                       |
| `lock_token`      | Token issued by the developer when a lock succeeds                                                  | String, 1–200 characters                                                                                    |
| `recipient`       | Map of fields identifying the receiving account                                                     | Object with string values. Field composition agreed with ONEitem per game (e.g., `{"account_id":"..."}`)    |

## 4. Integration Flows

#### 4.1 Account Linking

Linking a game account to a ONE store member starts with a **one-time link token issued by the game server**.

<figure><img src="https://2757207078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG1QmZshNU0saLqpjlDho%2Fuploads%2FPv2iWMd0K5xgUvxZeBlR%2Fsequence_edit_5_en.png?alt=media&amp;token=72903767-43fc-4be2-aded-69c7b29a9cd0" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="81">Step</th><th width="279">Direction</th><th width="269">Details</th><th>Developer implements</th></tr></thead><tbody><tr><td>①</td><td>Game Client → Game Server</td><td>Request link token (login session auth)</td><td>●</td></tr><tr><td>②</td><td>Game Server → Game Client</td><td>Return <code>token</code>, <code>expires_at</code> (valid 10 minutes)</td><td>●</td></tr><tr><td>③</td><td>Game Client → ONEitem SDK</td><td><code>ONEitemClient.open()</code> — gameId · gameLinkToken · gameUserId</td><td>●</td></tr><tr><td>④</td><td>ONEitem SDK</td><td>Check ONE store install·version (guide if missing or outdated)</td><td></td></tr><tr><td>⑤</td><td>ONEitem SDK → ONE store</td><td>Pass link token</td><td></td></tr><tr><td>⑥</td><td>ONE store</td><td>Login·member check, required consent</td><td></td></tr><tr><td>⑦</td><td>ONE store → ONEitem Server</td><td>Submit link token</td><td></td></tr><tr><td>⑧</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/link-tokens/exchanges</code> (X-API-Key auth)</td><td>●</td></tr><tr><td>⑨</td><td>Game Server → ONEitem Server</td><td>Return <code>server_id</code>, <code>game_account_id</code>, <code>expires_at</code></td><td>●</td></tr><tr><td>⑩</td><td>ONE store → ONEitem Server</td><td>Confirm link (member taps Link)</td><td></td></tr><tr><td>⑪</td><td>ONE store → ONEitem SDK</td><td>Return result (result codes under discussion)</td><td></td></tr><tr><td>⑫</td><td>ONEitem SDK → Game Client</td><td>Callback <code>ONEitemResult</code> (OK · USER_CANCELED · NOT_ELIGIBLE etc., under discussion)</td><td>●</td></tr><tr><td>⑬</td><td>Game Client → Game Server</td><td>Check link status (method TBD)</td><td>●</td></tr></tbody></table>

* **Server basis**: The linked server is determined by `server_id` in the ⑨ token exchange result. SDK `setServerName()` is the server name shown on the ONE store screen and is not used as a server ID.

Link token requirements:

<table><thead><tr><th width="236">Item</th><th>Requirement</th></tr></thead><tbody><tr><td>Issued for</td><td>The server and game account of the current login session. Do not trust an account ID sent by the client</td></tr><tr><td>Format</td><td>URL-safe string from at least 128 bits of cryptographic randomness, 16–512 characters. Must not reveal the game, server, or account</td></tr><tr><td>Validity</td><td>10 minutes after issuance</td></tr><tr><td>One-time use·re-exchange</td><td>Consumed by the first exchange. However, to handle lost responses, re-exchanging the same token before expiry returns the same account</td></tr><tr><td>Storage·logging</td><td>Store a hash instead of the raw token. Never write the raw token to logs or analytics events</td></tr><tr><td>Client handling</td><td>Do not put the token in URL query·fragment, browser storage, or clipboard</td></tr></tbody></table>

Whether issuing a new token for the same account invalidates previous tokens is up to the developer. Unlinking is handled by ONEitem, so there is no separate API.

#### 4.2 Overall Trade Flow

![A lock ends in exactly one of transfer or unlock](https://2757207078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG1QmZshNU0saLqpjlDho%2Fuploads%2FOWTOge17dhMEpZLSyydX%2FA%20lock%20ends%20in%20exactly%20one%20of%20transfer%20or%20unlock?alt=media\&token=34714275-ca5f-4fff-9fd1-9a071fd842f4)

<table><thead><tr><th width="103">Step</th><th>Details</th><th>API</th></tr></thead><tbody><tr><td>1</td><td>Inventory lookup</td><td><code>GET /v1/inventory</code></td></tr><tr><td>2</td><td>List for sale: lock quantity</td><td><code>POST /v1/locks</code> → <code>lock_token</code></td></tr><tr><td>3a</td><td>Purchase: validate recipient → transfer</td><td><code>POST /v1/recipients/validations</code>, <code>POST /v1/transfers</code></td></tr><tr><td>3b</td><td>Cancel sale: unlock</td><td><code>POST /v1/unlocks</code></td></tr><tr><td>Common</td><td>On lost response·timeout·503, look up the result with the same operation_key</td><td><code>GET /v1/operations</code></td></tr></tbody></table>

A lock ends in exactly one of 3a transfer or 3b unlock.

Quantities locked at listing go to the buyer via `transfers` when purchased, or back to the seller via `unlocks` when cancelled. Before a trade, maintenance status is checked with `GET /v1/status`.

#### 4.3 Sale Listing·Cancellation

A sale listing is confirmed only when the ⑨ lock returns `SUCCEEDED` and a `lock_token`.&#x20;

<figure><img src="https://2757207078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG1QmZshNU0saLqpjlDho%2Fuploads%2FF2j9PCSTbw5w9VPuKMnH%2Fsequence_edit_6_en.png?alt=media&amp;token=0fb71ea4-b167-4643-89c6-040cd32d0dd0" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="72">Step</th><th width="186">Direction</th><th width="288">Details</th><th>Developer implements</th></tr></thead><tbody><tr><td>①</td><td>Game Client → ONEitem SDK</td><td><code>ONEitemClient.open()</code> (includes link token, see 4.1)</td><td>●</td></tr><tr><td>②</td><td>ONE store → ONEitem Server</td><td>Enter sell screen (based on linked game account)</td><td></td></tr><tr><td>③</td><td>ONEitem Server → Game Server</td><td><code>GET /v1/status</code></td><td>●</td></tr><tr><td>④</td><td>Game Server → ONEitem Server</td><td><code>is_maintenance: false</code></td><td>●</td></tr><tr><td>⑤</td><td>ONEitem Server → Game Server</td><td><code>GET /v1/inventory</code> (server_id · game_account_id)</td><td>●</td></tr><tr><td>⑥</td><td>Game Server → ONEitem Server</td><td><code>items[]</code> (excluding locked quantity)</td><td>●</td></tr><tr><td>⑦</td><td>ONEitem Server → ONE store</td><td>Show sellable items</td><td></td></tr><tr><td>⑧</td><td>ONE store → ONEitem Server</td><td>List for sale (enter quantity·price)</td><td></td></tr><tr><td>⑨</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/locks</code> (operation_key · quantity · generation)</td><td>●</td></tr><tr><td>⑩</td><td>Game Server</td><td>Check ownership·available quantity, atomically lock only the selected quantity</td><td>●</td></tr><tr><td>⑪</td><td>Game Server → ONEitem Server</td><td><code>SUCCEEDED</code> + <code>lock_token</code></td><td>●</td></tr><tr><td>⑫</td><td>ONEitem Server → ONE store</td><td>Listing complete</td><td></td></tr><tr><td colspan="4"><strong>On sale cancellation</strong></td></tr><tr><td>⑬</td><td>ONE store → ONEitem Server</td><td>Cancel sale</td><td></td></tr><tr><td>⑭</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/unlocks</code> (operation_key · lock_token · generation)</td><td>●</td></tr><tr><td>⑮</td><td>Game Server → ONEitem Server</td><td><code>SUCCEEDED</code> (reserved quantity returned to seller)</td><td>●</td></tr></tbody></table>

* **③–⑥ Lookup**: When the sell screen opens, maintenance status and sellable inventory are looked up. Already locked quantities must be excluded from the list.
* **⑨–⑪ Lock**: Check ownership·available quantity and lock in one step; on success, always return a `lock_token`. If the same `operation_key` comes again, return the same result and the same token.
* **Lost response**: ONEitem does not lock again with a new key; it looks up the result with `GET /v1/operations`.
* **⑬–⑮ Cancellation**: Return only the reserved quantity of that lock to the seller. If the lock has already been transferred, respond with `FAILED`.

For request·response details, see 5.1, 5.2, 5.4, 5.6, 5.7.

#### 4.4 Purchase

A purchased item moves from seller to buyer in a single ⑧ transfer.&#x20;

<figure><img src="https://2757207078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FG1QmZshNU0saLqpjlDho%2Fuploads%2FUPOiOnlkUQWyVbidL37E%2Fsequence_edit_7_en.png?alt=media&amp;token=ff9e4f92-f978-4aee-9dc9-4c780e386aeb" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="78">Step</th><th width="262">Direction</th><th width="273">Details</th><th>Developer implements</th></tr></thead><tbody><tr><td>①</td><td>Game Client → ONEitem SDK</td><td><code>ONEitemClient.open()</code> (includes link token, see 4.1)</td><td>●</td></tr><tr><td>②</td><td>ONE store → ONEitem Server</td><td>Select product (enter server·receiving account)</td><td></td></tr><tr><td>③</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/recipients/validations</code> (server_id · recipient)</td><td>●</td></tr><tr><td>④</td><td>Game Server → ONEitem Server</td><td><code>masked_account</code> (on rejection: INVALID + reason)</td><td>●</td></tr><tr><td>⑤</td><td>ONEitem Server → ONE store</td><td>Show receiving account confirmation</td><td></td></tr><tr><td>⑥</td><td>ONE store</td><td>Payment (paid in ONE store)</td><td></td></tr><tr><td>⑦</td><td>ONE store → ONEitem Server</td><td>Send payment result</td><td></td></tr><tr><td>⑧</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/transfers</code> (operation_key · lock_token · recipient)</td><td>●</td></tr><tr><td>⑨</td><td>Game Server</td><td>Deduct seller reservation + grant to buyer (atomically, exactly once)</td><td>●</td></tr><tr><td>⑩</td><td>Game Server → ONEitem Server</td><td><code>SUCCEEDED</code></td><td>●</td></tr><tr><td>⑪</td><td>ONEitem Server → ONE store</td><td>Item delivered</td><td></td></tr><tr><td colspan="4"><strong>When transfer is confirmed FAILED</strong></td></tr><tr><td>–</td><td>ONEitem Server → Game Server</td><td><code>POST /v1/unlocks</code> (operation_key · lock_token · generation)</td><td>●</td></tr><tr><td>–</td><td>Game Server → ONEitem Server</td><td><code>SUCCEEDED</code> (reserved quantity returned to seller)</td><td>●</td></tr></tbody></table>

* **③–④ Recipient validation**: Only checks the receiving account; no item is moved. On rejection, `reason` is used for the message on the purchase screen.
* **⑧–⑩ Transfer**: Find seller·item·quantity from the `lock_token`, and atomically deduct the reservation and grant the item to the buyer. Even if the same request repeats, grant only once.
* **Lost response**: Look up the result with the same key. Do not refund or unlock based only on a timeout or `UNKNOWN`.
* **Transfer confirmed failed**: ONEitem releases the lock with `POST /v1/unlocks` and returns the quantity to the seller. Transfer and unlock can never both succeed.

For request·response details, see 5.3, 5.5, 5.6, 5.7.

## 5. API Reference

Account, item, and key values in the examples below are for illustration only.

Every request includes the `X-API-Key` header (see 3.2). Do not include fields not listed in the tables in requests or responses. String lengths are minimum–maximum characters.

#### 5.1 Maintenance Check — `GET /v1/status`

```
{
  "is_maintenance": false
}
```

**Request**: No parameters

**Response**

| Field            | Type    | Required | Description                                                  |
| ---------------- | ------- | -------- | ------------------------------------------------------------ |
| `is_maintenance` | boolean | Required | `true` during maintenance, `false` when trading is available |

* Return HTTP 200 with `"is_maintenance": true` even during maintenance.
* Maintenance status only indicates whether trading is currently available; it does not confirm the result of operations already requested.

#### 5.2 Inventory Lookup — `GET /v1/inventory`

Request: `GET /v1/inventory?server_id=s1&game_account_id=acct-seller` (both parameters required)

```
{
  "items": [
    {
      "inventory_ref": "inv-potion-hp-acct-seller",
      "developer_item_id": "potion-hp",
      "name": "HP Potion",
      "server_id": "s1",
      "quantity": "500",
      "attributes": {
        "grade": "rare"
      }
    }
  ]
}
```

**Request**

| In    | Field             | Type           | Required | Description                      |
| ----- | ----------------- | -------------- | -------- | -------------------------------- |
| query | `server_id`       | string (1–128) | Required | Game server to look up           |
| query | `game_account_id` | string (1–128) | Required | Seller's game account to look up |

**Response**

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>items</code></td><td>array</td><td>Required</td><td>List of held items. Empty array if none</td></tr><tr><td><code>items[].inventory_ref</code></td><td>string (1–128)</td><td>Required</td><td>Identifier of the held item. Must be unique within a response</td></tr><tr><td><code>items[].developer_item_id</code></td><td>string (1–128)</td><td>Required</td><td>Item definition ID (catalog item ID)</td></tr><tr><td><code>items[].name</code></td><td>string</td><td>Required</td><td>Item name</td></tr><tr><td><code>items[].server_id</code></td><td>string (1–128)</td><td>Required</td><td>Same value as the requested <code>server_id</code></td></tr><tr><td><code>items[].quantity</code></td><td>string</td><td>Required</td><td>Sellable quantity. Positive integer string, excluding locked quantity</td></tr><tr><td><code>items[].attributes</code></td><td>object (string values)</td><td>Required</td><td>Item attributes (grade, etc.). <code>{}</code> if none</td></tr></tbody></table>

* `items` and all 6 fields of each item are required. If there are no items, return `{"items": []}`; if there are no attributes, `"attributes": {}`.
* `inventory_ref` must not repeat within a response, and `server_id` must match the requested server.
* Exclude items with quantity 0, and exclude locked (on-sale) quantities.

#### 5.3 Recipient Validation — `POST /v1/recipients/validations`

```
{
  "server_id": "s1",
  "recipient": {
    "account_id": "acct-buyer"
  }
}
```

**Request**

| In   | Field       | Type                   | Required | Description                                                                |
| ---- | ----------- | ---------------------- | -------- | -------------------------------------------------------------------------- |
| body | `server_id` | string (1–128)         | Required | Game server that will receive the item                                     |
| body | `recipient` | object (string values) | Required | Receiving account fields entered by the buyer. Composition agreed per game |

**Response**: One of the two forms below

| Field            | Type   | Required             | Description                                        |
| ---------------- | ------ | -------------------- | -------------------------------------------------- |
| `masked_account` | string | Required if valid    | Receiving account display value shown to the buyer |
| `status`         | string | Required if rejected | Always `INVALID`                                   |
| `reason`         | string | Optional             | Rejection reason. See the table below              |

Return only one of the two forms; never mix them.

| Result        | Example response                                                          |
| ------------- | ------------------------------------------------------------------------- |
| Valid account | `{"masked_account": "pla***"}` — account display value shown to the buyer |
| Rejected      | `{"status": "INVALID", "reason": "GAME_ACCOUNT_NOT_FOUND"}`               |

| `reason`                 | Meaning                                   |
| ------------------------ | ----------------------------------------- |
| `GAME_ACCOUNT_NOT_FOUND` | The entered account does not exist        |
| `SERVER_MISMATCH`        | The account cannot receive on that server |
| `INVENTORY_FULL`         | Not enough storage space in the account   |

* `reason` is optional. If omitted or not in the list, it is treated as a rejection without a reason. The value is used for the error message on the purchase screen.
* This API does not report whether the account is the seller's own or whether maintenance is in progress.
* This step only validates and does not move items. Receivability is checked again at the actual transfer.

#### 5.4 Sale Quantity Lock — `POST /v1/locks`

```
// Request
{
  "operation_key": "sale/100/lock/1",
  "server_id": "s1",
  "game_account_id": "acct-seller",
  "inventory_ref": "inv-potion-hp-acct-seller",
  "quantity": "3",
  "generation": 1
}

// Response
{
  "status": "SUCCEEDED",
  "lock_token": "game-lock-token-01"
}
```

**Request**

| In   | Field             | Type                   | Required | Description                                     |
| ---- | ----------------- | ---------------------- | -------- | ----------------------------------------------- |
| body | `operation_key`   | string (1–256)         | Required | Operation key. Same value on retry              |
| body | `server_id`       | string (1–128)         | Required | Seller's game server                            |
| body | `game_account_id` | string (1–128)         | Required | Seller's game account                           |
| body | `inventory_ref`   | string (1–128)         | Required | Held item to lock (value from inventory lookup) |
| body | `quantity`        | string                 | Required | Quantity to lock. Positive integer string       |
| body | `generation`      | integer (1–4294967295) | Required | Lock generation. Value fixed by ONEitem         |

**Response**

| Field        | Type           | Required            | Description                                                  |
| ------------ | -------------- | ------------------- | ------------------------------------------------------------ |
| `status`     | string         | Required            | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (see 6.2)   |
| `lock_token` | string (1–200) | Required on success | Lock token issued by the developer. Used for transfer·unlock |

* After checking ownership and available quantity, **atomically** lock only the requested quantity. Locked quantities are excluded from in-game use, movement, and other sales.
* On success, `lock_token` **must** be returned (optional in the schema, but required for a successful lock). A result lookup with the same operation key returns the same token.
* The token is bound to the game, owner, item, quantity, and generation.

#### 5.5 Item Transfer — `POST /v1/transfers`

```
// Request
{
  "operation_key": "order/200/transfer/1",
  "lock_token": "game-lock-token-01",
  "generation": 1,
  "recipient_server_id": "s1",
  "recipient": {
    "account_id": "acct-buyer"
  }
}

// Response
{
  "status": "SUCCEEDED"
}
```

**Request**

| In   | Field                 | Type                   | Required | Description                                                         |
| ---- | --------------------- | ---------------------- | -------- | ------------------------------------------------------------------- |
| body | `operation_key`       | string (1–256)         | Required | Operation key. Same value on retry                                  |
| body | `lock_token`          | string (1–200)         | Required | Token received when the lock succeeded                              |
| body | `generation`          | integer (1–4294967295) | Required | Same generation as the lock                                         |
| body | `recipient_server_id` | string (1–128)         | Required | Game server where the buyer receives the item                       |
| body | `recipient`           | object (string values) | Required | Receiving account fields (same composition as recipient validation) |

**Response**

| Field    | Type   | Required | Description                                                |
| -------- | ------ | -------- | ---------------------------------------------------------- |
| `status` | string | Required | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (see 6.2) |

* Seller, item, and quantity are found from the `lock_token`. The request contains no quantity.
* Bundle seller reservation deduction + buyer grant + marking the lock as transferred + recording the operation result into **a single atomic operation**.
* Grant only once even if the same request repeats. Do not transfer a lock that has already been released or has a different generation.

#### 5.6 Unlock — `POST /v1/unlocks`

```
// Request
{
  "operation_key": "sale/100/unlock/1",
  "lock_token": "game-lock-token-01",
  "generation": 1
}

// Response
{
  "status": "SUCCEEDED"
}
```

**Request**

| In   | Field           | Type                   | Required | Description                        |
| ---- | --------------- | ---------------------- | -------- | ---------------------------------- |
| body | `operation_key` | string (1–256)         | Required | Operation key. Same value on retry |
| body | `lock_token`    | string (1–200)         | Required | Token of the lock to release       |
| body | `generation`    | integer (1–4294967295) | Required | Same generation as the lock        |

**Response**

| Field    | Type   | Required | Description                                                                                                   |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `status` | string | Required | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (see 6.2). `FAILED` if the lock has already been transferred |

* Return only the reserved quantity of that token·generation to the seller.
* **Transfer and unlock can never both succeed.** Unlocking a lock that has already been transferred returns `FAILED`, and items granted to the buyer are not reclaimed.
* While the transfer result is unknown, do not release the lock based only on your own timer.

#### 5.7 Operation Result Lookup — `GET /v1/operations`

Request: `GET /v1/operations?operation_key=sale%2F100%2Flock%2F1`

```
{
  "status": "SUCCEEDED",
  "lock_token": "game-lock-token-01"
}
```

**Request**

| In    | Field           | Type           | Required | Description                           |
| ----- | --------------- | -------------- | -------- | ------------------------------------- |
| query | `operation_key` | string (1–256) | Required | Operation key to look up. URL-encoded |

**Response**

| Field        | Type           | Required    | Description                                                                              |
| ------------ | -------------- | ----------- | ---------------------------------------------------------------------------------------- |
| `status`     | string         | Required    | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (see 6.2)                               |
| `lock_token` | string (1–200) | Conditional | Required if the lock operation is `SUCCEEDED`. Same value as the originally issued token |

* URL-encode the operation key as a query value. Even if it contains `/`, do not append it to the path.
* A successful lock result includes the original `lock_token`. Transfer·unlock results do not need it.
* For status meanings, see section 6.

#### 5.8 Link Token Exchange — `POST /v1/link-tokens/exchanges`

```
// Request
{
  "token": "example-link-token-0001"
}

// Response
{
  "server_id": "s1",
  "game_account_id": "acct-seller",
  "expires_at": "2026-10-27T03:10:00Z"
}
```

**Request**

| In   | Field   | Type            | Required | Description                                                          |
| ---- | ------- | --------------- | -------- | -------------------------------------------------------------------- |
| body | `token` | string (16–512) | Required | One-time link token issued by the developer. Never log the raw value |

**Response**: One of the two forms below

| Field             | Type                   | Required            | Description                                                        |
| ----------------- | ---------------------- | ------------------- | ------------------------------------------------------------------ |
| `server_id`       | string (0–128)         | Required if valid   | Server bound to the token. Empty string if the game has no servers |
| `game_account_id` | string (1–128)         | Required if valid   | Game account of the login session that issued the token            |
| `expires_at`      | string (RFC 3339, UTC) | Required if valid   | Token expiry time                                                  |
| `status`          | string                 | Required if invalid | Always `INVALID`                                                   |
| `reason`          | string                 | Optional            | `TOKEN_NOT_FOUND` (never issued) · `TOKEN_EXPIRED` (expired)       |

| Situation                                                 | Response                                                                    |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| Valid token (first exchange or re-exchange before expiry) | 200, `server_id`·`game_account_id`·`expires_at`. Same values on re-exchange |
| Never issued                                              | 200, `{"status": "INVALID", "reason": "TOKEN_NOT_FOUND"}`                   |
| Expired                                                   | 200, `{"status": "INVALID", "reason": "TOKEN_EXPIRED"}`                     |
| Under maintenance                                         | 503, `{"code": "GAME_MAINTENANCE"}`                                         |
| Format error·authentication failure                       | 400·401                                                                     |

* Games without servers set `server_id` to an empty string. `expires_at` is in UTC, RFC 3339 format.
* For token issuing requirements, see 4.1 Account Linking.

## 6. Response Handling and Reliability Requirements

Business results are always delivered as **HTTP 200 + body**. Any other response is treated as a communication or request problem, and does not by itself confirm a failed trade.

#### 6.1 HTTP Status Codes

| Status                                   | Meaning                                                                    | ONEitem handling                                                                |
| ---------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 200                                      | Business result (decided by body)                                          | Handled by the `status` in the body                                             |
| 400                                      | Missing required value·format error                                        | Check the request                                                               |
| 401                                      | Key missing·invalid                                                        | Check the connection settings                                                   |
| 409                                      | Same operation key reused for a different request (`OPERATION_KEY_REUSED`) | No asset change                                                                 |
| 503 + `GAME_MAINTENANCE`                 | Explicit maintenance                                                       | Treated as maintenance; state-changing requests are reconciled by result lookup |
| 503 (other)·other errors·connection lost | Temporary failure                                                          | Result unknown → reconcile with `GET /v1/operations`                            |

Error body format: `{"code": "GAME_MAINTENANCE", "message": "game under maintenance"}`. `code` is required, `message` is optional; branch only on `code`.

#### 6.2 Operation Result Status (`status`)

Lock, transfer, unlock, and result lookup return one of the following statuses.

| Status      | Meaning                          | What the developer guarantees                                                   |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------- |
| `SUCCEEDED` | Completed                        | Never executed again with the same key. Lock results include the original token |
| `FAILED`    | Confirmed not executed           | Keep the failure record so the key never succeeds later                         |
| `UNKNOWN`   | Execution unknown or in progress | Do not assume it was not executed                                               |
| `NOT_FOUND` | No record for the key            | Do not rule out a delayed request arriving later                                |

Do not decide refunds, unlocks, or resending with a new operation key based only on a timeout, `UNKNOWN`, or `NOT_FOUND`. ONEitem looks up the result again with the same key.

#### 6.3 Mandatory Implementation Requirements

1. **Idempotency**: Put a unique constraint on `operation_key` and compare the operation type and request content. Lock, transfer, and unlock share the same key space.
   * Same key + same request → return the stored result as is
   * Same key + different request → 409
   * Differences in JSON whitespace or field order are not treated as a different request
2. **Atomicity**: Process the asset change and saving the operation result in the same transaction (or an equivalently recoverable procedure). Even if the process stops before responding, a retry must not grant twice.
3. **Token binding**: A `lock_token` is valid only for one game and one generation. Never overwrite the token's owner, item, or quantity with request values.
4. **Race handling**: If transfer and unlock arrive at the same time, let only one succeed. Do not record `FAILED` just because an error response was sent.
5. **Persistence**: Operation results must remain queryable after restart or redeployment. Use in-memory storage for testing only.
