---
title: "Get ban status for a user"
method: GET
path: "/users/{address}/bans"
tags: ["Platform Moderation"]
---

# Get ban status for a user

`GET /users/{address}/bans`

Returns whether the specified user address would currently be rejected by a platform
ban — its own, or one matching the device the address is recorded on.

This endpoint is **public** — no authentication required. It is intended for
clients to check their own ban status before attempting to connect.

### Close to what token retrieval enforces, but not identical

This endpoint receives only an address, so its device term is always the address's **last
recorded** device. Token paths prefer the device identifier the request itself carries and
fall back to the recorded one only when it has none. Where a request arrives with a device
that differs from the recorded one, the two can disagree in both directions.

So a user banned on one wallet who reconnects under a different wallet from the same
recorded device is reported as banned here and rejected at token issuance — but treat this
endpoint as the source for **user-facing ban messaging**, not as a prediction of whether a
specific connection will be accepted. Token issuance stays authoritative for a concrete
request.

### The ban record is only returned for the address's own ban

`matchedOn` says which identifier matched. When it is `device`, the response contains
`isBanned: true` and no `ban` object: the matching row belongs to another player, and
publishing it on an unauthenticated route would disclose whose wallet is banned. The full
record — reason, expiry, custom message — is returned only when `matchedOn` is `address`.
Where both exist, the address's own ban is the one reported.

`bannedDeviceId` is **never** returned on this route, whatever `matchedOn` says: it is a
stable cross-wallet machine identifier and this endpoint is unauthenticated. Moderator
tooling reads it from the moderator-gated `GET /bans`.

A client can use `matchedOn` to word the notice: an `address` match has a reason and an
expiry to show, a `device` match has neither.

Because the route is unauthenticated, any address can be tested for device coverage. That
is an accepted trade-off for being able to tell banned players why they are blocked.

Moderator tooling that needs the full picture, including each ban's device snapshot,
should use the moderator-gated `GET /bans`.

## Path parameters

- `address` string, required

## Response `200`

Ban status retrieved

- object
  - `data` object
    - `isBanned` boolean
    - `matchedOn` 'address' | 'device' — Which identifier the ban matched on. `address` is the player's own ban and comes with the full `ban` record. `device` means another player's ban covers the device this address is recorded on; `ban` is omitted, because that record belongs to someone else. Absent when `isBanned` is false.
    - `ban` object — A ban record without the device id, as returned by the public `GET /users/{address}/bans`. Declared standalone rather than as `UserBan` minus a field, so no generator can flatten a composed schema and hand the device id back to a public client. `UserBan` is this plus `bannedDeviceId`.
      - `id` string — Unique ban record identifier
      - `bannedAddress` string — Ethereum address of the banned user
      - `bannedBy` string — Ethereum address of the moderator who issued the ban
      - `reason` string — Internal reason for the ban
      - `customMessage` string, nullable — Optional message shown to the player on rejection
      - `bannedAt` string, date-time — When the ban was issued
      - `expiresAt` string, date-time, nullable — When the ban expires. Null for permanent bans.
      - `liftedAt` string, date-time, nullable — When the ban was manually lifted, if applicable
      - `liftedBy` string, nullable — Ethereum address of the moderator who lifted the ban
      - `createdAt` string, date-time — Record creation timestamp

## Other responses

- `500` — Internal server error

---

[API](https://skmtc.net/decentraland/apis/realm-provider-api.md) · [All operations](https://skmtc.net/decentraland/apis/realm-provider-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/decentraland/realm-provider-api/revisions/d94e0e0f1821/schema)