Protocol v1 payload reference

This page is for connector diagnostics and protocol maintenance. A server owner does not need these payloads to connect or configure a server: connector code parses and serializes them before integration code or configured SQL runs.

Common delivery envelope

Every paid game change has a stable command id for replay handling, its parent order id, the normalized target, and one versioned grant object.

Item delivery command

{
  "commandId": "77e6a4f0-4f6b-4c85-9e37-1d2a55f0a001",
  "orderId": "b1c9c6a2-8d33-4f1e-9b70-6c0d64f0a002",
  "grantActionId": "5a3f2d10-91ab-4d4f-8c22-7e9b64f0a003",
  "target": {
    "normalizedAccountName": "hero01",
    "characterId": 268480001
  },
  "grant": {
    "type": "l2.grant_item",
    "schemaVersion": 1,
    "itemId": 57,
    "count": 1000
  }
}

enchantLevel is optional and defaults to 0. A bundle uses one order id and one command id per grant line. Replay protection is keyed by command id.

Other grant objects

Skill

{ "type": "l2.grant_skill", "schemaVersion": 1, "skillId": 1204, "skillLevel": 1 }

Character rename

{ "type": "l2.character_rename", "schemaVersion": 1, "newName": "Ravenblade" }

Gender change

{ "type": "l2.gender_change", "schemaVersion": 1, "newSex": "female" }

Dragon Coins

{ "type": "m2.grant_cash", "schemaVersion": 1, "amount": 5000 }

Dragon Marks

{ "type": "m2.grant_mileage", "schemaVersion": 1, "amount": 250 }

The outer envelope remains the same. Account-scoped grants omit the character target when the game operation does not use one.

Character and catalog rows

Character summary

{
  "characterId": 268437506,
  "name": "Ravenblade",
  "level": 40,
  "classId": 88,
  "race": "human",
  "sex": "male",
  "online": true,
  "pvpKills": 3,
  "pkKills": 0,
  "clanName": null
}

Item catalog row

{ "itemId": 57, "name": "Adena", "type": "EtcItem", "grade": null, "stackable": true }

Skill catalog row

{ "skillId": 1204, "name": "Wind Walk", "maxLevel": 1 }

Character skills query

Query payload

{ "normalizedAccountName": "hero01", "characterId": 268480001 }

Successful result

{
  "outcome": "OK",
  "skills": [
    { "skillId": 3, "level": 9 },
    { "skillId": 1040, "level": 3 }
  ]
}

Player-online event

{
  "protocolVersion": 1,
  "messageId": "7ef143bc-5810-4b10-9507-820e72b13ce1",
  "gameServerId": "834a9e80-607b-46b4-8952-cb27d2a476c9",
  "sentAt": "2026-07-30T12:00:00.000Z",
  "type": "event.player_online",
  "payload": {
    "normalizedAccountName": "admin",
    "characterId": 268473216
  }
}

Protocol v1 retains these shapes for compatibility. Public integration APIs use domain objects or profile rows instead of constructing this JSON.

Marketplace inventory and withdrawal

Inventory results describe whether an item is safe to transfer. objectId is optional for aggregate stack rows; location, icon, and name may be null.

Inventory row

{
  "objectId": 12345,
  "itemId": 4037,
  "count": 1,
  "stackable": false,
  "enchantLevel": 0,
  "equipped": false,
  "location": "INVENTORY",
  "fidelity": "TRANSFERABLE",
  "icon": null,
  "name": "Blessed Scroll"
}

Only TRANSFERABLE, unequipped rows in INVENTORY can enter escrow. The withdrawal carries the item instance selected by the player:

Withdrawal command payload

{
  "commandId": "77e6a4f0-4f6b-4c85-9e37-1d2a55f0a001",
  "escrowId": "b1c9c6a2-8d33-4f1e-9b70-6c0d64f0a002",
  "withdrawActionId": "5a3f2d10-91ab-4d4f-8c22-7e9b64f0a003",
  "target": { "normalizedAccountName": "hero01", "characterId": 268480001 },
  "item": {
    "type": "l2.withdraw_item",
    "schemaVersion": 1,
    "itemId": 4037,
    "count": 1,
    "objectId": 12345
  }
}

An APPLIED withdrawal includes withdrawnJson. The Java core creates this evidence only after its independent inventory reads prove the exact item id, count, enchant level, instance id when pinned, transfer fidelity, equipment state, and location. The portal rejects incomplete or mismatched evidence into reconciliation instead of crediting the vault.