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": "robert",
    "characterId": 268485666
  },
  "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": "robert", "characterId": 268485666 }

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.