For the complete documentation index, see llms.txt. This page is also available as Markdown.

Studio Operators

What a studio's operators use to give their players credits out of the studio's budget

The studios the signing wallet acts for (studio operator)

get
/operator/studios

Requires signed fetch. Answers every studio the signing wallet is an operator of (an empty list for a wallet that is not one), with what its operators see of it, and the ceiling for a single grant.

Authorizations
AuthorizationstringRequired

Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.

Responses
200

The wallet's studios

application/json
get/operator/studios
GET /operator/studios HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "studios": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "status": "active",
      "balanceCents": 1,
      "grantedCents": 1,
      "grantCount": 1
    }
  ],
  "grantLimits": {
    "maxGrantCents": null
  }
}

One of the signing wallet's studios, with its grants (studio operator)

get
/operator/studios/{studioId}

Requires signed fetch from a wallet that acts for the studio; any other wallet is answered 404. Answers the studio, a page of its grants (newest first) and the ceiling for a single grant. Deposits and adjustments, and who made them, are not shown to operators.

Authorizations
AuthorizationstringRequired

Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.

Path parameters
studioIdstring · uuidRequired
Query parameters
limitinteger · min: 1 · max: 200OptionalDefault: 50
offsetintegerOptionalDefault: 0
Responses
200

The studio and its grants

application/json
get/operator/studios/{studioId}
GET /operator/studios/{studioId} HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "studio": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "status": "active",
    "balanceCents": 1,
    "grantedCents": 1,
    "grantCount": 1
  },
  "grants": [
    {
      "creditId": "text",
      "recipient": "text",
      "usdCents": 1,
      "reason": null,
      "grantedBy": "text",
      "createdAt": 1
    }
  ],
  "page": {
    "limit": 1,
    "offset": 1,
    "total": 1
  },
  "grantLimits": {
    "maxGrantCents": null
  }
}

Grant credits out of a studio's budget (studio operator)

post
/operator/studios/{studioId}/grants

A studio operator gives a player Shop credits (1 credit = 10 cents) out of the studio's budget. Requires signed fetch from a wallet that acts for the studio; that wallet is recorded as the granter. A wallet that does not is answered 404, as if the studio did not exist, and that is checked before anything else, a past grant included. Whether it still acts for the studio is checked again where the grant is written.

The credits do not expire and are written with credit_source = studio_grant: they appear in GET /credits like any grant (its default listing, with no source, shows them next to admin grants, with the operator as granter; source=studio_grant or source=grant tells them apart), and are not counted against the daily ceiling for admin grants. No daily ceiling applies: a studio may give all of its budget at once, and the budget is what bounds it (new budget has its own daily ceiling). A single grant may give at most STUDIO_GRANT_MAX_CENTS (fail-closed: grants are refused with a 503 while it is unset). The grant is refused when USD credits are disabled, when it is above that ceiling, when the studio is paused, when the player is one of the studio's operators (the granter included), when the studio's balance does not cover it, and, judged last so the refusal cannot be used to look a flag up, when the player cannot receive a studio's credits. The studio's checks are made in the transaction that writes the grant, under the studio's lock, so concurrent grants cannot overdraw a budget, and adding or removing an operator waits for a grant in flight.

Idempotent on idempotencyKey: repeating a request with the same key and body answers 200 with replayed: true and the credit the first request granted, and writes nothing. A repeat is answered before any check that only applies to a new grant, so it is answered even if the studio has since been paused or emptied, the player flagged, USD credits turned off or the ceiling lowered. The same key with a different body is refused. Keys are unique per studio, not per operator: another operator of the same studio repeating a key with the same body is answered the same grant. A new grant is announced on Slack and published as an ON_DEMAND_CREDITS_GRANTED event whose metadata also carries studioId and studioName; a replay is not.

Each operator wallet may send at most STUDIO_GRANT_RATE_LIMIT grants (60 by default) per STUDIO_GRANT_RATE_WINDOW_SECONDS (60 by default); past that it is answered 429 with Retry-After, and nothing is written.

Authorizations
AuthorizationstringRequired

Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44l). Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. See http://adr.decentraland.org/adr/ADR-44l for details.

Path parameters
studioIdstring · uuidRequired
Body
addressstringRequired

The player's wallet

Pattern: ^0x[a-fA-F0-9]{40}$
creditsinteger · min: 1Required

At most STUDIO_GRANT_MAX_CENTS / 10 (see grantLimits on GET /admin/studios/{studioId})

reasonstring · max: 80Required

Trimmed, a single line; recorded on the grant and on the studio's budget entry

annotationstring · max: 200 · nullableOptional

Trimmed, a single line of printable characters; recorded on the grant

idempotencyKeystringRequired

The caller's key for this grant, e.g. a new UUID; reuse it only to retry it

Pattern: ^[A-Za-z0-9._:-]{8,128}$
Responses
200

The key already made this grant; nothing new was written

application/json
creditIdstringRequired
studioIdstring · uuidRequired
addressstringRequired
denominationstring · enumRequiredPossible values:
creditsintegerRequired
usdCentsintegerRequired
balanceCentsintegerRequired

The studio's balance now (after the grant, or as it stands on a replay)

replayedbooleanRequired

True when the idempotency key had already made this grant

post/operator/studios/{studioId}/grants
POST /operator/studios/{studioId}/grants HTTP/1.1
Host: credits.decentraland.org
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
  "credits": 300,
  "reason": "Top player of the week",
  "idempotencyKey": "3d1c0f5e-8b2a-4f6e-9c7d-1a2b3c4d5e6f"
}
{
  "creditId": "text",
  "studioId": "123e4567-e89b-12d3-a456-426614174000",
  "address": "text",
  "denomination": "USD",
  "credits": 1,
  "usdCents": 1,
  "balanceCents": 1,
  "replayed": true
}

Last updated