Operations · SGIP

Joining

`hub.hello@1`

Platform → HubRequired

Payload

Field	Type	Notes
`name`required	string	max 60 characters
`icon`	string	max 8 characters
`inbox`required	string
`visit`	string
`public_key`required	string
`capabilities`required	op[]

Result

Field	Type	Notes
`registered`required	object
`platform_id`required	platformId
`hub_public_key`required	string

Example

payload

{
  "name": "Berlin Days",
  "icon": "🐻",
  "inbox": "https://berlin.example/sgip/inbox",
  "visit": "https://berlin.example/sgip/visit",
  "public_key": "A6EHv/POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg=",
  "capabilities": [
    "hub.ping@1",
    "player.lookup@1",
    "message.send@1",
    "visit.end@1"
  ]
}

result

{
  "registered": true,
  "platform_id": "berlin.example",
  "hub_public_key": "1A4Pun+lbVo1w72cjWIq2WRNyVw+1DT4PehBGHINEts="
}

JSON Schema

`hub.ping@1`

BothRequired

Health check, in either direction.

Payload

An empty object.

Result

Field	Type	Notes
`platform`required	string
`time`required	timestamp

Example

payload

{}

result

{
  "platform": "berlin.example",
  "time": "2026-10-09T12:00:00Z"
}

JSON Schema

`hub.check@1`

Platform → Hub

Platform → Hub. Ask the hub to test this platform against the contract (section 9.1). Signed with the platform's own key; only the platform can ask for its own check.

Payload

An empty object.

Result

Field	Type	Notes
`conforms`required	boolean
`checks`required	object[]
`checks[].name`required	string
`checks[].passed`required	boolean
`checks[].required`required	boolean
`checks[].detail`required	string

Example

payload

{}

result

{
  "conforms": true,
  "checks": [
    {
      "name": "Descriptor is served",
      "passed": true,
      "required": true,
      "detail": "https://berlin.example/.well-known/sgip.json"
    },
    {
      "name": "Answers a hub-signed hub.ping@1",
      "passed": true,
      "required": true,
      "detail": ""
    },
    {
      "name": "Rejects a replayed nonce",
      "passed": true,
      "required": true,
      "detail": ""
    },
    {
      "name": "Visit page loads",
      "passed": true,
      "required": false,
      "detail": "https://berlin.example/sgip/visit answered 200."
    }
  ]
}

JSON Schema

`platform.directory@1`

Platform → Hub

List registered platforms so a UI can hide buttons a target cannot handle.

Payload

An empty object.

Result

Field	Type	Notes
`platforms`required	object[]
`platforms[].platform_id`required	platformId
`platforms[].name`required	string
`platforms[].icon`	string \| null
`platforms[].icon_url`	string \| null
`platforms[].capabilities`required	op[]
`platforms[].visit_url`	string \| null
`platforms[].return_url`	string \| null
`platforms[].origin`	string \| null
`platforms[].embed`	object
`platforms[].embed.allowed`	boolean
`platforms[].currencies`	currency[]
`platforms[].accepts`	object[]	The money this game accepts from visitors (section 7.4)
`platforms[].accepts[].from`required	platformId
`platforms[].accepts[].give`required	money	In the home currency
`platforms[].accepts[].get`required	money	What `give` buys here, in this game's currency
`platforms[].accepts[].daily_inflow_limit`required	money	The most that may enter from this game per UTC day, in `get`'s currency
`platforms[].visitors_welcome`	boolean	Whether players from the game asking may visit this one (section 7.5)

Example

payload

{}

result

{
  "platforms": [
    {
      "platform_id": "lagos.example",
      "name": "Lagos Stories",
      "icon": "🌴",
      "capabilities": [
        "message.send@1",
        "visit.end@1"
      ],
      "visit_url": "https://lagos.example/sgip/visit",
      "origin": "https://lagos.example",
      "embed": {
        "allowed": true
      },
      "visitors_welcome": true
    }
  ]
}

JSON Schema

Players

`player.lookup@1`

Platform → Hub → PlatformRequired

Public profile of a discoverable player. not_found for players who have not opted in.

Payload

Field	Type	Notes
`player`required	playerAddress

Result

Field	Type	Notes
`player`required	playerAddress
`sub`required	string
`display_name`required	string
`avatar`	object
`badges`	string[]

Example

payload

{
  "player": "lena@berlin.example"
}

result

{
  "player": "lena@berlin.example",
  "sub": "01JA00000000000000000000SB",
  "display_name": "Lena from Kreuzberg",
  "avatar": {
    "color": "#e76f51"
  },
  "badges": [
    "newcomer"
  ]
}

JSON Schema

`player.profile@1`

Platform → Hub → Platform

A player's public card: what other games may show about them. Platforms MUST answer not_found for players who are not discoverable, exactly as player.lookup@1 does.

Payload

Field	Type	Notes
`player`required	playerAddress

Result

Field	Type	Notes
`player`required	playerAddress
`display`required	display
`bio`	string	max 280 characters
`since`	timestamp
`career`	object
`career.field`	careerField
`career.title`required	string	max 60 characters
`career.level`	integer
`career.top_level`	integer
`skills`	object[]
`skills[].skill`required	skill
`skills[].level`required	integer	0–10
`home`	string	The district they live in, never an exact home address.. max 60 characters
`presence`	presence

Example

payload

{
  "player": "lena@berlin.example"
}

result

{
  "player": "lena@berlin.example",
  "display": {
    "name": "Lena from Kreuzberg",
    "color": "#e76f51",
    "badges": [
      "Newcomer"
    ]
  },
  "since": "2026-10-08T22:09:50Z",
  "career": {
    "field": "technology",
    "title": "Developer",
    "level": 1,
    "top_level": 4
  },
  "skills": [
    {
      "skill": "coding",
      "level": 4
    },
    {
      "skill": "music",
      "level": 2
    }
  ],
  "home": "Kreuzberg",
  "presence": "online"
}

JSON Schema

`presence.update@1`

Platform → Hub → subscribersQueued if offline

A player's presence changed. Only sent for discoverable players; the hub fans it out to subscribers.

Payload

Field	Type	Notes
`player`required	playerAddress
`status`required	presence
`activity`	object	What they are doing, if they share it.
`activity.verb`required	verb
`activity.label`	string	max 60 characters
`activity.place`	placeAddress
`activity.pose`	pose

Result

An empty object.

Example

payload

{
  "player": "lena@berlin.example",
  "status": "online",
  "activity": {
    "verb": "eat",
    "label": "Currywurst at the Imbiss",
    "pose": "stand"
  }
}

result

{}

JSON Schema

`presence.subscribe@1`

Platform → Hub

Receive presence.update@1 for these players.

Payload

Field	Type	Notes
`players`required	playerAddress[]

Result

Field	Type	Notes
`subscribed`required	integer

Example

payload

{
  "players": [
    "tunde@lagos.example"
  ]
}

result

{
  "subscribed": 1
}

JSON Schema

Messages and invites

`message.send@1`

Platform → Hub → PlatformRequiredQueued if offline

A direct message between players. Envelope from.player and to.player are required.

Payload

Field	Type	Notes
`text`required	plainText
`from_name`	string	max 60 characters
`lang`	string	max 12 characters

Result

An empty object.

Example

payload

{
  "text": "How far? Greetings from Lagos",
  "from_name": "Tunde",
  "lang": "en"
}

result

{
  "delivered": true
}

JSON Schema

`message.receipt@1`

Platform → Hub → PlatformQueued if offline

Delivered or read receipts for messages the recipient got.

Payload

Field	Type	Notes
`message_ids`required	ulid[]
`status`required	`"delivered"` \| `"read"`

Result

An empty object.

Example

payload

{
  "message_ids": [
    "01JA0000000000000000000011"
  ],
  "status": "read"
}

result

{
  "updated": 1
}

JSON Schema

`invite.send@1`

Platform → Hub → PlatformQueued if offline

Invite a player to visit the sender's game.

Payload

Field	Type	Notes
`invite_id`required	ulid
`from_name`	string	max 60 characters
`host`required	platformId
`place`	placeAddress
`note`	string	max 200 characters
`expires_at`	timestamp

Result

An empty object.

Example

payload

{
  "invite_id": "01JA00000000000000000000N1",
  "from_name": "Lena",
  "host": "berlin.example",
  "place": "place://berlin.example/mitte/hauptbahnhof",
  "note": "Currywurst is on me",
  "expires_at": "2026-10-10T12:00:00Z"
}

result

{
  "received": true
}

JSON Schema

`invite.respond@1`

Platform → Hub → PlatformQueued if offline

Accept or decline an invite.

Payload

Field	Type	Notes
`invite_id`required	ulid
`accepted`required	boolean

Result

An empty object.

Example

payload

{
  "invite_id": "01JA00000000000000000000N1",
  "accepted": true
}

result

{}

JSON Schema

Visits

`visit.request@1`

Home → Hub

Get (or refresh, with the same visit_id) a passport and launch URL for a host platform.

Payload

Field	Type	Notes
`player`required	playerAddress
`sub`required	string	max 64 characters
`host`required	platformId
`visit_id`	ulid
`arrival`	placeAddress
`scopes`	scope[]
`display`	display
`budget`	money	Sent with the pay scope: the most the host may charge on this visit, in a home currency

Result

Field	Type	Notes
`visit_id`required	ulid
`passport`required	string
`launch_url`required	string
`host_origin`	string
`host_name`	string
`expires_at`required	integer	When the passport expires, in Unix seconds: its `exp` claim
`embed`	object
`embed.allowed`	boolean

Example

payload

{
  "player": "tunde@lagos.example",
  "sub": "01JA00000000000000000000SB",
  "host": "berlin.example",
  "scopes": [
    "visit",
    "chat",
    "act"
  ],
  "display": {
    "name": "Tunde",
    "color": "#2e4a6b"
  }
}

result

{
  "visit_id": "01JA00000000000000000000V1",
  "passport": "eyJhbGciOiJFZERTQSJ9.e30.c2ln",
  "launch_url": "https://berlin.example/sgip/visit",
  "host_origin": "https://berlin.example",
  "host_name": "Berlin Days",
  "expires_at": 1791480900,
  "embed": {
    "allowed": true
  }
}

JSON Schema

`visit.end@1`

Host → Hub → HomeQueued if offline

The visit is over; the home game takes the player back and caps each souvenir at ±20.

Payload

Field	Type	Notes
`visit_id`required	ulid
`player`required	playerAddress
`reason`required	`"left"` \| `"idle"` \| `"removed"` \| `"expired"`
`duration_s`	integer
`minutes`	integer	Game minutes that passed for the guest
`souvenirs`	statChanges
`last_place`	placeAddress
`summary`	string	max 200 characters
`activities`	object[]	What the guest did, by verb, so the home game can tell the story.
`activities[].verb`required	verb
`activities[].count`required	integer

Result

An empty object.

Example

payload

{
  "visit_id": "01JA00000000000000000000V1",
  "player": "tunde@lagos.example",
  "reason": "left",
  "duration_s": 640,
  "minutes": 120,
  "souvenirs": {
    "mood": 12,
    "hunger": -8
  },
  "last_place": "place://berlin.example/kreuzberg/kneipe-am-kanal",
  "activities": [
    {
      "verb": "drink",
      "count": 1
    },
    {
      "verb": "explore",
      "count": 2
    }
  ]
}

result

{
  "returned": true
}

JSON Schema

`travel.quote@1`

Platform → Hub → Platform

Where a traveller would arrive in the host game, and how long it takes. The fare is charged by the game the player leaves.

Payload

Field	Type	Notes
`mode`required	transportMode
`from`	placeAddress

Result

Field	Type	Notes
`mode`required	transportMode
`arrival`required	placeAddress
`arrival_name`	string
`duration_minutes`	integer
`gateways`	object[]

Example

payload

{
  "mode": "flight",
  "from": "place://lagos.example/ikeja/airport"
}

result

{
  "mode": "flight",
  "arrival": "place://berlin.example/mitte/hauptbahnhof",
  "arrival_name": "Berlin Hauptbahnhof",
  "duration_minutes": 420
}

JSON Schema

The world

`world.places@1`

Platform → Hub → Platform

A platform's public places.

Payload

An empty object.

Result

Field	Type	Notes
`places`required	object[]
`places[].id`required	placeAddress
`places[].name`required	string
`places[].district`	string
`places[].kind`required	placeKind
`places[].lat`	number
`places[].lng`	number
`places[].gateway`	boolean
`places[].guests_allowed`	boolean
`places[].capacity`	integer
`places[].hours`	array \| null
`places[].osm`	string	The OpenStreetMap element it came from, like node/1504407936.

Example

payload

{}

result

{
  "places": [
    {
      "id": "place://berlin.example/kreuzberg/kneipe-am-kanal",
      "name": "Kneipe am Kanal",
      "district": "kreuzberg",
      "kind": "pub",
      "lat": 52.4966,
      "lng": 13.4244,
      "gateway": false,
      "guests_allowed": true,
      "capacity": 60,
      "hours": [
        16,
        26
      ]
    }
  ]
}

JSON Schema

`place.status@1`

Platform → Hub → Platform

How a place is right now: open or shut, how busy, how many players are there. Cheap to answer; meant for "is it worth going?" before a visit.

Payload

Field	Type	Notes
`place`required	placeAddress

Result

Field	Type	Notes
`place`required	placeAddress
`kind`	placeKind
`open`required	boolean
`busyness`	number	0 empty, 1 packed.. 0–1
`players`	integer	Players there now, counting visitors. A count only, never who.
`opens_at`	timestamp
`closes_at`	timestamp
`events`	string[]	Ids of world.events@1 events on now.

Example

payload

{
  "place": "place://berlin.example/neukoelln/stadtbad"
}

result

{
  "place": "place://berlin.example/neukoelln/stadtbad",
  "kind": "swimming_pool",
  "open": true,
  "busyness": 0.6,
  "players": 3,
  "closes_at": "2026-10-09T20:00:00Z"
}

JSON Schema

`world.events@1`

Platform → Hub → Platform

What is on at a platform: concerts, matches, market days, weddings. Lets other games show "what's on in Berlin tonight" and invite players to it.

Payload

Field	Type	Notes
`from`	timestamp
`to`	timestamp
`kind`	eventKind
`limit`	integer	1–100

Result

Field	Type	Notes
`events`required	object[]
`events[].id`required	string	max 64 characters
`events[].kind`required	eventKind
`events[].title`required	string	max 80 characters
`events[].description`	string	max 500 characters
`events[].place`required	placeAddress
`events[].starts_at`required	timestamp
`events[].ends_at`	timestamp
`events[].price`	money
`events[].verb`	verb
`events[].game`	gameKind
`events[].guests_allowed`	boolean	Whether visitors from other games may attend.

Example

payload

{
  "kind": "match"
}

result

{
  "events": [
    {
      "id": "berlin-derby",
      "kind": "match",
      "title": "The Berlin derby",
      "place": "place://berlin.example/koepenick/stadium",
      "starts_at": "2026-10-10T15:30:00Z",
      "ends_at": "2026-10-10T17:30:00Z",
      "price": {
        "amount": 2500,
        "currency": "EUR"
      },
      "verb": "watch",
      "guests_allowed": true
    }
  ]
}

JSON Schema

`action.list@1`

Platform → Hub → Platform

What a guest can do at a place, in shared verbs and stats.

Payload

Field	Type	Notes
`place`required	placeAddress

Result

Field	Type	Notes
`place`required	placeAddress
`actions`required	object[]
`actions[].id`required	string
`actions[].verb`required	verb
`actions[].label`required	string
`actions[].duration_minutes`required	integer
`actions[].price`required	money
`actions[].pays`	money \| null
`actions[].effects`required	statChanges
`actions[].tags`	verb[]	More verbs that also describe it (a pub quiz: play, talk).
`actions[].pose`	pose
`actions[].skills`	object	Skill points it trains.
`actions[].interaction`	interaction
`actions[].game`	gameKind
`actions[].guests_allowed`	boolean	Hosts SHOULD list only what guests may do; this flags the rest when they are shown.

Example

payload

{
  "place": "place://berlin.example/kreuzberg/kneipe-am-kanal"
}

result

{
  "place": "place://berlin.example/kreuzberg/kneipe-am-kanal",
  "actions": [
    {
      "id": "beer",
      "verb": "drink",
      "label": "Glass of Berliner Pils",
      "duration_minutes": 40,
      "price": {
        "amount": 450,
        "currency": "EUR"
      },
      "pays": null,
      "effects": {
        "mood": 10,
        "social": 15,
        "energy": -5
      },
      "pose": "sit",
      "tags": [
        "talk"
      ]
    }
  ]
}

JSON Schema

Money

`wallet.balance@1`

Host → Hub

Host → Hub. What a visitor can spend, in each of the host's currencies that has a rate for the budget's currency (section 7.4).

Payload

Field	Type	Notes
`player`required	playerAddress
`visit_id`required	ulid

Result

Field	Type	Notes
`spendable`required	money[]

Example

payload

{
  "player": "tunde@lagos.example",
  "visit_id": "01JA00000000000000000000V1"
}

result

{
  "spendable": [
    {
      "amount": 10000,
      "currency": "EUR"
    }
  ]
}

JSON Schema

`wallet.charge@1`

Host → Hub

Host → Hub. Charge a visitor's home money for something they chose. The envelope id is the charge id (section 7.4).

Payload

Field	Type	Notes
`player`required	playerAddress
`visit_id`required	ulid
`amount`required	money	In one of the host's currencies
`description`required	string	max 120 characters
`verb`	verb

Result

Field	Type	Notes
`charge_id`required	ulid
`charged`required	money
`debited`required	money	What the home game took, in its currency
`spendable`required	money[]

Example

payload

{
  "player": "tunde@lagos.example",
  "visit_id": "01JA00000000000000000000V1",
  "amount": {
    "amount": 450,
    "currency": "EUR"
  },
  "description": "Glass of Berliner Pils",
  "verb": "drink"
}

result

{
  "charge_id": "01JA2B3C4D5E6F7G8H9J0K1M2N",
  "charged": {
    "amount": 450,
    "currency": "EUR"
  },
  "debited": {
    "amount": 225000,
    "currency": "NGN"
  },
  "spendable": [
    {
      "amount": 9550,
      "currency": "EUR"
    }
  ]
}

JSON Schema

`wallet.refund@1`

Host → Hub

Host → Hub. Return all or part of a charge within 24 hours. Without an amount, returns whatever remains (section 7.4).

Payload

Field	Type	Notes
`charge_id`required	ulid
`amount`	money	In the charge's currency; at most what remains unrefunded
`reason`	string	max 120 characters

Result

Field	Type	Notes
`refund_id`required	ulid
`refunded`required	money
`credited`required	money	What the home game returned, in its currency

Example

payload

{
  "charge_id": "01JA2B3C4D5E6F7G8H9J0K1M2N",
  "amount": {
    "amount": 450,
    "currency": "EUR"
  },
  "reason": "Closed before it was served"
}

result

{
  "refund_id": "01JA2B3C4D5E6F7G8H9J0K1M3P",
  "refunded": {
    "amount": 450,
    "currency": "EUR"
  },
  "credited": {
    "amount": 225000,
    "currency": "NGN"
  }
}

JSON Schema

`wallet.read@1`

Hub → Home

Hub → Home. A player's balance in one currency (section 7.4).

Payload

Field	Type	Notes
`player`required	playerAddress
`currency`required	currency

Result

Field	Type	Notes
`balance`required	money

Example

payload

{
  "player": "tunde@lagos.example",
  "currency": "NGN"
}

result

{
  "balance": {
    "amount": 50000000,
    "currency": "NGN"
  }
}

JSON Schema

`wallet.debit@1`

Hub → Home

Hub → Home. Take an amount if the player has it, in one step, or answer insufficient_funds. A repeated charge_id is the same debit; a charge_id already voided by wallet.credit@1 is refused (section 7.4).

Payload

Field	Type	Notes
`charge_id`required	ulid
`player`required	playerAddress
`amount`required	money
`host`required	platformId
`host_amount`required	money
`description`required	string	max 120 characters

Result

Field	Type	Notes
`balance`required	money

Example

payload

{
  "charge_id": "01JA2B3C4D5E6F7G8H9J0K1M2N",
  "player": "tunde@lagos.example",
  "amount": {
    "amount": 225000,
    "currency": "NGN"
  },
  "host": "berlin.example",
  "host_amount": {
    "amount": 450,
    "currency": "EUR"
  },
  "description": "Glass of Berliner Pils"
}

result

{
  "balance": {
    "amount": 49775000,
    "currency": "NGN"
  }
}

JSON Schema

`wallet.credit@1`

Hub → Home

Hub → Home. Return a refunded or voided amount. A repeated refund_id is the same credit. For a charge_id never debited, record it and refuse any later debit with that id (section 7.4).

Payload

Field	Type	Notes
`charge_id`required	ulid
`refund_id`required	ulid
`player`required	playerAddress
`amount`required	money

Result

Field	Type	Notes
`balance`required	money

Example

payload

{
  "charge_id": "01JA2B3C4D5E6F7G8H9J0K1M2N",
  "refund_id": "01JA2B3C4D5E6F7G8H9J0K1M3P",
  "player": "tunde@lagos.example",
  "amount": {
    "amount": 225000,
    "currency": "NGN"
  }
}

result

{
  "balance": {
    "amount": 50000000,
    "currency": "NGN"
  }
}

JSON Schema

Joining

#hub.hello@1

Payload

Result

#hub.ping@1

Payload

Result

#hub.check@1

Payload

Result

#platform.directory@1

Payload

Result

Players

#player.lookup@1

Payload

Result

#player.profile@1

Payload

Result

#presence.update@1

Payload

Result

#presence.subscribe@1

Payload

Result

Messages and invites

#message.send@1

Payload

Result

#message.receipt@1

Payload

Result

#invite.send@1

Payload

Result

#invite.respond@1

Payload

Result

Visits

#visit.request@1

Payload

Result

#visit.end@1

Payload

Result

#travel.quote@1

Payload

Result

The world

#world.places@1

Payload

Result

#place.status@1

Payload

Result

#world.events@1

Payload

Result

#action.list@1

Payload

Result

Money

#wallet.balance@1

Payload

Result

#wallet.charge@1

Payload

Result

#wallet.refund@1

Payload

Result

#wallet.read@1

Payload

Result

#wallet.debit@1

Payload

Result

#wallet.credit@1

Payload

`hub.hello@1`

`hub.ping@1`

`hub.check@1`

`platform.directory@1`

`player.lookup@1`

`player.profile@1`

`presence.update@1`

`presence.subscribe@1`

`message.send@1`

`message.receipt@1`

`invite.send@1`

`invite.respond@1`

`visit.request@1`

`visit.end@1`

`travel.quote@1`

`world.places@1`

`place.status@1`

`world.events@1`

`action.list@1`

`wallet.balance@1`

`wallet.charge@1`

`wallet.refund@1`

`wallet.read@1`

`wallet.debit@1`

`wallet.credit@1`