# dev.cocore.account.tokenGrant

> Published by [cocore.dev](https://lexicon.garden/identity/did:plc:5quuhkmwe2q4k3azfsgg7kdz)

✓ This is the authoritative definition for this NSID.

## Description

Records that an exchange has issued its one-time signup token grant to a recipient DID. Written by the exchange to its own PDS on the first balance event for a given DID — receipt as either side, top-up, or admission check. Issued exactly once per (exchange, recipient) pair. A consumer reconstructing balances offline starts each DID at this grant amount; absence of a tokenGrant record means the DID has never interacted with the exchange.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenGrant)
- [Documentation](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenGrant/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:5quuhkmwe2q4k3azfsgg7kdz/dev.cocore.account.tokenGrant/examples)

## Definitions

### `dev.cocore.account.tokenGrant`

**Type**: `record`

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `amount` | `integer` | Yes | Tokens credited. Equal to the `tokenGrant` field of the policy in effect at issuance time. |
| `policy` | `ref` → `com.atproto.repo.strongRef` | Yes | Strong-ref to the exchangePolicy in effect when the grant was issued. Auditors verify `amount` against the policy's `tokenGrant`. |
| `exchange` | `string` (did) | Yes | Exchange DID. MUST equal the repo this record is published in. |
| `createdAt` | `string` (datetime) | Yes |  |
| `recipient` | `string` (did) | Yes | The DID receiving the grant. |

## Raw Schema

```json
{
  "id": "dev.cocore.account.tokenGrant",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "exchange",
          "recipient",
          "amount",
          "policy",
          "createdAt"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 0,
            "description": "Tokens credited. Equal to the `tokenGrant` field of the policy in effect at issuance time."
          },
          "policy": {
            "ref": "com.atproto.repo.strongRef",
            "type": "ref",
            "description": "Strong-ref to the exchangePolicy in effect when the grant was issued. Auditors verify `amount` against the policy's `tokenGrant`."
          },
          "exchange": {
            "type": "string",
            "format": "did",
            "description": "Exchange DID. MUST equal the repo this record is published in."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "recipient": {
            "type": "string",
            "format": "did",
            "description": "The DID receiving the grant."
          }
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "Records that an exchange has issued its one-time signup token grant to a recipient DID. Written by the exchange to its own PDS on the first balance event for a given DID — receipt as either side, top-up, or admission check. Issued exactly once per (exchange, recipient) pair. A consumer reconstructing balances offline starts each DID at this grant amount; absence of a tokenGrant record means the DID has never interacted with the exchange."
}
```