> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dropkit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Queries

> Query tokens, get token details, and retrieve token statistics

## Token Queries

Query tokens and their related data using GraphQL.

## Basic Token Queries

### Get Single Token

Retrieve a specific token by ID.

```graphql theme={null}
query GetToken($id: ID!) {
  token(id: $id) {
    id
    name
    symbol
    decimals
    totalSupply
    address
    description
    imageUrl
    curveId
    isExternal
    status

    # Deployment information
    packageId
    treasuryCapId
    coinMetadataId
    upgradeCapId
    deploymentTxHash

    # Distribution buckets
    communityDropsReserve
    publicSaleReserve
    creatorReserve
    dropkitTreasuryReserve
    liquidityMarketingReserve

    # Vesting information
    creatorVestingStart
    creatorVestingCliff
    creatorVestingEnd
    dropkitVestingStart
    dropkitVestingEnd
    hasInitialDistribution

    # Timestamps
    createdAt
    updatedAt

    # Relations
    creator {
      id
      username
      displayName
      avatar
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "id": "token_abc123"
}
```

**Response:**

```json theme={null}
{
  "data": {
    "token": {
      "id": "token_abc123",
      "name": "Community Token",
      "symbol": "COMM",
      "decimals": 9,
      "totalSupply": "1000000000000000",
      "address": "0x123abc...",
      "description": "A token for our community",
      "imageUrl": "https://example.com/token-image.png",
      "curveId": "curve_xyz789",
      "isExternal": false,
      "status": "DEPLOYED",
      "packageId": "0x456def...",
      "treasuryCapId": "0x789ghi...",
      "coinMetadataId": "0xabcjkl...",
      "upgradeCapId": "0xdefmno...",
      "deploymentTxHash": "0x123abc...",
      "communityDropsReserve": "500000000000000",
      "publicSaleReserve": "300000000000000",
      "creatorReserve": "150000000000000",
      "dropkitTreasuryReserve": "25000000000000",
      "liquidityMarketingReserve": "25000000000000",
      "creatorVestingStart": "2024-01-01T00:00:00Z",
      "creatorVestingCliff": "2024-03-01T00:00:00Z",
      "creatorVestingEnd": "2024-12-31T23:59:59Z",
      "dropkitVestingStart": "2024-01-01T00:00:00Z",
      "dropkitVestingEnd": "2024-06-30T23:59:59Z",
      "hasInitialDistribution": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T12:00:00Z",
      "creator": {
        "id": "user_xyz789",
        "username": "creator123",
        "displayName": "Creator Name",
        "avatar": "https://example.com/avatar.png"
      }
    }
  }
}
```

### List Tokens

Get multiple tokens with filtering and pagination.

```graphql theme={null}
query GetTokens($limit: Int, $offset: Int, $createdByMe: Boolean) {
  tokens(limit: $limit, offset: $offset, createdByMe: $createdByMe) {
    id
    name
    symbol
    decimals
    totalSupply
    address
    description
    imageUrl
    status
    isExternal
    createdAt
    creator {
      id
      username
      displayName
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "limit": 10,
  "offset": 0,
  "createdByMe": true
}
```

### Get My Tokens

Retrieve all tokens created by the authenticated user.

```graphql theme={null}
query GetMyTokens {
  myTokens {
    id
    name
    symbol
    decimals
    totalSupply
    address
    description
    imageUrl
    status
    isExternal
    curveId

    # Distribution buckets
    communityDropsReserve
    publicSaleReserve
    creatorReserve
    dropkitTreasuryReserve
    liquidityMarketingReserve

    # Vesting status
    creatorVestingStart
    creatorVestingEnd
    hasInitialDistribution

    createdAt
    updatedAt
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "myTokens": [
      {
        "id": "token_abc123",
        "name": "Community Token",
        "symbol": "COMM",
        "decimals": 9,
        "totalSupply": "1000000000000000",
        "address": "0x123abc...",
        "description": "A token for our community",
        "imageUrl": "https://example.com/token-image.png",
        "status": "DEPLOYED",
        "isExternal": false,
        "curveId": "curve_xyz789",
        "communityDropsReserve": "500000000000000",
        "publicSaleReserve": "300000000000000",
        "creatorReserve": "150000000000000",
        "dropkitTreasuryReserve": "25000000000000",
        "liquidityMarketingReserve": "25000000000000",
        "creatorVestingStart": "2024-01-01T00:00:00Z",
        "creatorVestingEnd": "2024-12-31T23:59:59Z",
        "hasInitialDistribution": true,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T12:00:00Z"
      }
    ]
  }
}
```

## Advanced Token Queries

### Token with Complete Information

Get a token with all its related data and computed fields.

```graphql theme={null}
query GetTokenWithDetails($id: ID!) {
  token(id: $id) {
    id
    name
    symbol
    decimals
    totalSupply
    address
    description
    imageUrl
    curveId
    isExternal
    status

    # Deployment information
    packageId
    treasuryCapId
    coinMetadataId
    upgradeCapId
    deploymentTxHash

    # Distribution buckets (amounts)
    communityDropsReserve
    publicSaleReserve
    creatorReserve
    dropkitTreasuryReserve
    liquidityMarketingReserve

    # Vesting schedule
    creatorVestingStart
    creatorVestingCliff
    creatorVestingEnd
    dropkitVestingStart
    dropkitVestingEnd
    hasInitialDistribution

    # Timestamps
    createdAt
    updatedAt

    # Creator information
    creator {
      id
      username
      displayName
      bio
      avatar
      createdAt
    }
  }
}
```

### Multiple Token Queries

Get different token sets in one request.

```graphql theme={null}
query GetMultipleTokenSets {
  allTokens: tokens(limit: 20) {
    id
    name
    symbol
    status
    creator {
      username
    }
  }

  myTokens: myTokens {
    id
    name
    symbol
    status
    totalSupply
    communityDropsReserve
  }

  deployedTokens: tokens(limit: 10) {
    id
    name
    symbol
    status
    address
    deploymentTxHash
  }
}
```

## Token Status Filtering

### Get Tokens by Status

Query tokens filtered by their deployment status.

```graphql theme={null}
# Note: Status filtering would need to be added to the schema
query GetTokensByStatus {
  pendingTokens: tokens(limit: 10) {
    id
    name
    symbol
    status
    createdAt
  }

  deployedTokens: tokens(limit: 10) {
    id
    name
    symbol
    status
    address
    deploymentTxHash
  }
}
```

## Error Handling

### Token Not Found

```graphql theme={null}
query GetNonExistentToken {
  token(id: "nonexistent") {
    id
    name
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "token": null
  }
}
```

### Invalid Token ID

```graphql theme={null}
query GetInvalidTokenId {
  token(id: "") {
    id
    name
  }
}
```

**Response:**

```json theme={null}
{
  "errors": [
    {
      "message": "Token ID is required",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["token"]
    }
  ],
  "data": {
    "token": null
  }
}
```

## Best Practices

### 1. Request Only Needed Fields

```graphql theme={null}
# Good: Request only what you need
query GetTokenBasics {
  myTokens {
    id
    name
    symbol
    status
  }
}

# Avoid: Requesting all fields when not needed
query GetAllTokenData {
  myTokens {
    id
    name
    symbol
    decimals
    totalSupply
    address
    description
    imageUrl
    # ... many other fields
  }
}
```

### 2. Use Pagination for Large Lists

```graphql theme={null}
query GetTokensPaginated($limit: Int, $offset: Int) {
  tokens(limit: $limit, offset: $offset) {
    id
    name
    symbol
    createdAt
  }
}
```

### 3. Combine Related Queries

```graphql theme={null}
query TokenDashboard {
  myTokens {
    id
    name
    symbol
    status
    totalSupply
    communityDropsReserve
    creator {
      displayName
    }
  }

  # Could also get related drops
  myDrops {
    id
    title
    token {
      id
      name
      symbol
    }
  }
}
```

## Common Use Cases

### Token Portfolio View

```graphql theme={null}
query TokenPortfolio {
  myTokens {
    id
    name
    symbol
    decimals
    totalSupply
    status
    imageUrl
    description

    # Distribution information
    communityDropsReserve
    publicSaleReserve
    creatorReserve

    # Vesting information
    creatorVestingStart
    creatorVestingEnd
    hasInitialDistribution

    createdAt
  }
}
```

### Token Creation Status

```graphql theme={null}
query TokenCreationStatus {
  myTokens {
    id
    name
    symbol
    status
    deploymentTxHash
    address
    packageId
    createdAt
    updatedAt
  }
}
```

### Token Details for Drop Creation

```graphql theme={null}
query TokensForDropCreation {
  myTokens {
    id
    name
    symbol
    decimals
    totalSupply
    status
    address
    communityDropsReserve
    # Only show tokens that can be used for drops
  }
}
```

### Token Trading Information

```graphql theme={null}
query TokenTradingInfo($id: ID!) {
  token(id: $id) {
    id
    name
    symbol
    decimals
    totalSupply
    address
    curveId
    isExternal

    # Distribution buckets for trading analysis
    communityDropsReserve
    publicSaleReserve
    liquidityMarketingReserve

    creator {
      username
      displayName
    }
  }
}
```

### Token Verification

```graphql theme={null}
query VerifyToken($id: ID!) {
  token(id: $id) {
    id
    name
    symbol
    status
    address
    packageId
    deploymentTxHash
    isExternal

    creator {
      id
      username
      displayName
    }
  }
}
```