Drop Management Mutations

Manage drops with GraphQL mutations for creating, updating, and deleting drops.

Create Drop

Create a new drop with an existing token.

mutation CreateDrop($input: CreateDropInput!) {
  createDrop(input: $input) {
    id
    title
    description
    status
    type
    claimType
    maxAmount
    tokenAmount
    shortcode
    imageUrl
    price
    supply
    estimatedValueUsd
    claimDeadline
    isActive
    createdAt
    updatedAt
    creator {
      id
      username
      displayName
    }
    token {
      id
      name
      symbol
      address
    }
  }
}

Variables:

{
  "input": {
    "title": "Community Token Drop",
    "description": "A drop for early supporters",
    "type": "TOKEN",
    "claimType": "REGULAR",
    "maxAmount": "100000",
    "tokenAmount": "100",
    "existingTokenId": "token_abc123",
    "estimatedValueUsd": 10.0,
    "claimDeadline": "2024-12-31T23:59:59Z",
    "status": "ACTIVE",
    "shortcode": "community-drop",
    "imageUrl": "https://example.com/drop-image.png"
  }
}

Response:

{
  "data": {
    "createDrop": {
      "id": "drop_xyz789",
      "title": "Community Token Drop",
      "description": "A drop for early supporters",
      "status": "ACTIVE",
      "type": "TOKEN",
      "claimType": "REGULAR",
      "maxAmount": "100000",
      "tokenAmount": "100",
      "shortcode": "community-drop",
      "imageUrl": "https://example.com/drop-image.png",
      "price": null,
      "supply": null,
      "estimatedValueUsd": 10.0,
      "claimDeadline": "2024-12-31T23:59:59Z",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "creator": {
        "id": "user_abc123",
        "username": "creator123",
        "displayName": "Creator Name"
      },
      "token": {
        "id": "token_abc123",
        "name": "Community Token",
        "symbol": "COMM",
        "address": "0x123abc..."
      }
    }
  }
}

Update Drop

Update an existing drop’s properties.

mutation UpdateDrop($id: ID!, $input: UpdateDropInput!) {
  updateDrop(id: $id, input: $input) {
    id
    title
    description
    status
    maxAmount
    tokenAmount
    estimatedValueUsd
    claimDeadline
    imageUrl
    price
    supply
    updatedAt
  }
}

Variables:

{
  "id": "drop_xyz789",
  "input": {
    "title": "Updated Community Token Drop",
    "description": "Updated description for the drop",
    "status": "PAUSED",
    "maxAmount": "150000",
    "estimatedValueUsd": 15.0,
    "imageUrl": "https://example.com/updated-drop-image.png"
  }
}

Response:

{
  "data": {
    "updateDrop": {
      "id": "drop_xyz789",
      "title": "Updated Community Token Drop",
      "description": "Updated description for the drop",
      "status": "PAUSED",
      "maxAmount": "150000",
      "tokenAmount": "100",
      "estimatedValueUsd": 15.0,
      "claimDeadline": "2024-12-31T23:59:59Z",
      "imageUrl": "https://example.com/updated-drop-image.png",
      "price": null,
      "supply": null,
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Delete Drop

Delete a drop permanently.

mutation DeleteDrop($id: ID!) {
  deleteDrop(id: $id)
}

Variables:

{
  "id": "drop_xyz789"
}

Response:

{
  "data": {
    "deleteDrop": true
  }
}

Update Drop Key

Rotate the private key for a drop (for security purposes).

mutation UpdateDropKey($input: UpdateDropKeyInput!) {
  updateDropKey(input: $input) {
    success
    newPublicKey
    newPrivateKey
    transactionDigest
    error
  }
}

Variables:

{
  "input": {
    "dropId": "drop_xyz789",
    "reason": "Security rotation - compromised key",
    "newPrivateKey": "0x1234567890abcdef..."
  }
}

Response:

{
  "data": {
    "updateDropKey": {
      "success": false,
      "newPublicKey": null,
      "newPrivateKey": null,
      "transactionDigest": null,
      "error": "Key rotation not yet implemented in GraphQL - use the REST endpoint for now"
    }
  }
}

Input Types

CreateDropInput

input CreateDropInput {
  title: String! # Display name for the drop
  description: String # Optional description
  claimType: ClaimType! # Type of claim (REGULAR, STREAK, etc.)
  maxAmount: String! # Maximum claimable amount
  tokenAmount: String # Amount per claim (e.g., "100" or "0" for random)
  estimatedValueUsd: Float # Estimated USD value
  claimDeadline: DateTime # Optional deadline
  status: DropStatus # Initial status (defaults to ACTIVE)
  shortcode: String # Custom shortcode (auto-generated if not provided)
  imageUrl: String # Drop image URL
  price: Float # Price per item (for paid drops)
  supply: Int # Total supply
  type: DropType! # TOKEN or NFT
  tokenSymbol: String # Token symbol (deprecated, use existingTokenId)
  gatingId: String # Optional gating configuration ID
  communityId: String # Optional community ID
  existingTokenId: String # Required: ID of existing token
  tokenName: String # Token name (deprecated, use existingTokenId)
  tokenDescription: String # Token description (deprecated, use existingTokenId)
}

UpdateDropInput

input UpdateDropInput {
  title: String # Update display name
  description: String # Update description
  claimType: ClaimType # Update claim type
  maxAmount: String # Update maximum claimable amount
  tokenAmount: String # Update amount per claim
  estimatedValueUsd: Float # Update estimated USD value
  claimDeadline: DateTime # Update deadline
  status: DropStatus # Update status
  imageUrl: String # Update image URL
  price: Float # Update price per item
  supply: Int # Update total supply
}

UpdateDropKeyInput

input UpdateDropKeyInput {
  dropId: ID! # ID of the drop to update
  reason: String! # Reason for key rotation
  newPrivateKey: String # Optional new private key
}

Error Handling

Drop Not Found

mutation UpdateNonExistentDrop {
  updateDrop(id: "nonexistent", input: { title: "New Title" }) {
    id
    title
  }
}

Response:

{
  "errors": [
    {
      "message": "Drop not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["updateDrop"]
    }
  ],
  "data": {
    "updateDrop": null
  }
}

Access Denied

mutation UpdateUnauthorizedDrop {
  updateDrop(id: "drop_xyz789", input: { title: "Unauthorized Update" }) {
    id
    title
  }
}

Response:

{
  "errors": [
    {
      "message": "Access denied",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["updateDrop"]
    }
  ],
  "data": {
    "updateDrop": null
  }
}

Invalid Input

mutation CreateInvalidDrop {
  createDrop(
    input: {
      title: ""
      type: TOKEN
      claimType: REGULAR
      maxAmount: "100000"
      existingTokenId: "nonexistent"
    }
  ) {
    id
    title
  }
}

Response:

{
  "errors": [
    {
      "message": "Token not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["createDrop"]
    }
  ],
  "data": {
    "createDrop": null
  }
}

Best Practices

1. Always Use Existing Tokens

# Good: Use existing token ID
mutation CreateDropWithExistingToken {
  createDrop(
    input: {
      title: "My Drop"
      type: TOKEN
      claimType: REGULAR
      maxAmount: "100000"
      existingTokenId: "token_abc123"
    }
  ) {
    id
    title
  }
}

# Avoid: Don't try to create tokens inline
mutation CreateDropWithoutToken {
  createDrop(
    input: {
      title: "My Drop"
      type: TOKEN
      claimType: REGULAR
      maxAmount: "100000"
      tokenName: "My Token"
      tokenSymbol: "MTK"
    }
  ) {
    id
    title
  }
}

2. Handle Errors Gracefully

mutation CreateDropSafely($input: CreateDropInput!) {
  createDrop(input: $input) {
    id
    title
    status
    # Include error-relevant fields
    creator {
      id
      username
    }
    token {
      id
      name
      status
    }
  }
}

3. Update Only Changed Fields

# Good: Update only what changed
mutation UpdateDropTitle($id: ID!, $title: String!) {
  updateDrop(id: $id, input: { title: $title }) {
    id
    title
    updatedAt
  }
}

# Avoid: Sending all fields when only one changed
mutation UpdateDropFull($id: ID!) {
  updateDrop(
    id: $id
    input: {
      title: "New Title"
      description: "Same description"
      maxAmount: "Same amount"
      # ... other unchanged fields
    }
  ) {
    id
    title
  }
}

Common Use Cases

Create NFT Drop

mutation CreateNFTDrop {
  createDrop(
    input: {
      title: "Genesis NFT Collection"
      description: "Limited edition NFT collection"
      type: NFT
      claimType: REGULAR
      maxAmount: "1000"
      tokenAmount: "1"
      existingTokenId: "token_nft123"
      price: 5.0
      supply: 1000
      imageUrl: "https://example.com/nft-collection.png"
    }
  ) {
    id
    title
    shortcode
    supply
    price
  }
}

Create Token Drop with Gating

mutation CreateGatedTokenDrop {
  createDrop(
    input: {
      title: "VIP Token Drop"
      description: "Exclusive drop for VIP members"
      type: TOKEN
      claimType: ELITE
      maxAmount: "50000"
      tokenAmount: "500"
      existingTokenId: "token_vip123"
      gatingId: "gating_vip_rules"
      estimatedValueUsd: 50.0
    }
  ) {
    id
    title
    shortcode
    gatingConfig {
      isActive
      rules {
        description
      }
    }
  }
}

Pause and Resume Drop

mutation PauseDrop($id: ID!) {
  updateDrop(id: $id, input: { status: PAUSED }) {
    id
    status
    isActive
  }
}

mutation ResumeDrop($id: ID!) {
  updateDrop(id: $id, input: { status: ACTIVE }) {
    id
    status
    isActive
  }
}

Update Drop Details

mutation UpdateDropDetails($id: ID!) {
  updateDrop(
    id: $id
    input: {
      title: "Updated Drop Title"
      description: "New description with more details"
      imageUrl: "https://example.com/new-image.png"
      estimatedValueUsd: 25.0
      claimDeadline: "2024-12-31T23:59:59Z"
    }
  ) {
    id
    title
    description
    imageUrl
    estimatedValueUsd
    claimDeadline
    updatedAt
  }
}

GraphQL Documentation

Queries

Mutations

Types & Schema

Drop Management Mutations

Drop Management Mutations

Create Drop

Update Drop

Delete Drop

Update Drop Key

Input Types

CreateDropInput

UpdateDropInput

UpdateDropKeyInput

Error Handling

Drop Not Found

Access Denied

Invalid Input

Best Practices

1. Always Use Existing Tokens

2. Handle Errors Gracefully

3. Update Only Changed Fields

Common Use Cases

Create NFT Drop

Create Token Drop with Gating

Pause and Resume Drop

Update Drop Details

GraphQL Documentation

Queries

Mutations

Types & Schema

​Drop Management Mutations

​Create Drop

​Update Drop

​Delete Drop

​Update Drop Key

​Input Types

​CreateDropInput

​UpdateDropInput

​UpdateDropKeyInput

​Error Handling

​Drop Not Found

​Access Denied

​Invalid Input

​Best Practices

​1. Always Use Existing Tokens

​2. Handle Errors Gracefully

​3. Update Only Changed Fields

​Common Use Cases

​Create NFT Drop

​Create Token Drop with Gating

​Pause and Resume Drop

​Update Drop Details

Drop Management Mutations

Create Drop

Update Drop

Delete Drop

Update Drop Key

Input Types

CreateDropInput

UpdateDropInput

UpdateDropKeyInput

Error Handling

Drop Not Found

Access Denied

Invalid Input

Best Practices

1. Always Use Existing Tokens

2. Handle Errors Gracefully

3. Update Only Changed Fields

Common Use Cases

Create NFT Drop

Create Token Drop with Gating

Pause and Resume Drop

Update Drop Details