Skip to main content

⚠️ Gas Usage Limit Warnings

Welcome to the guide for understanding and managing gas usage limits in the Token City Blockchain API.

🌟 Objective: Monitor your gas usage to avoid service interruptions and ensure continuous blockchain operations.

📚 OpenAPI Documentation​

✨ Overview​

Our systems implement gas usage limits for each client to ensure fair resource allocation and optimal blockchain performance. You'll receive warnings when approaching your limit through two channels:

  1. Response Warnings: Direct feedback on transaction endpoints
  2. Webhook Notifications: Proactive alerts via GAS_USAGE_HIGH events

📊 Gas Limit Monitoring​

Understanding Gas Usage​

Gas is consumed by every blockchain transaction you execute:

  • Token Mints: ~150,000 - 300,000 gas
  • Token Transfers: ~100,000 - 200,000 gas
  • Token Burns: ~80,000 - 150,000 gas
  • Identity Operations: ~200,000 - 500,000 gas
  • Contract Deployments: ~2,000,000 - 5,000,000 gas

Your cumulative gas usage is tracked against your allocated limit.

📝 Implementation Guide​

Step 1: Check Transaction Responses​

Every transaction endpoint returns warnings when you're approaching your gas limit.

Example: Mint Token Request

Endpoint: POST /erc3643/{tokenId}/mint

Request Body:

{
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "amount": "1000000000000000000"
}

Response with Warning:

{
  "id": "tx_123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "message": "Transaction submitted",
  "warnings": [
    {
      "code": "GAS_LIMIT_WARNING",
      "message": "Gas usage at 97.9% of limit, contact us to increase the limit",
      "severity": "high",
      "context": {
        "tenantId": "tenant_abc123",
        "projectedUsage": 244663636440869594,
        "limit": 250000000000000000,
        "threshold": 80
      },
      "timestamp": "2025-10-20T10:12:15.716Z"
    }
  ]
}

Warning Fields Explained:

  • code: Warning type identifier (GAS_LIMIT_WARNING)
  • message: Human-readable warning description
  • severity: Warning level (low, medium, high, critical)
  • projectedUsage: Your current cumulative gas usage
  • limit: Your allocated gas limit
  • threshold: Percentage threshold that triggered the warning (80%)
  • timestamp: When the warning was generated

Step 2: Subscribe to Gas Usage Webhooks​

Receive proactive notifications when gas usage exceeds 80% of your limit.

Endpoint: POST /subscriptions/webhooks

Request Body:

{
  "event": "GAS_USAGE_HIGH",
  "callbackUrl": "https://your-server.com/webhooks/gas-alerts"
}

Response:

{
  "id": "sub_456e7890-e89b-12d3-a456-426614174111",
  "event": "GAS_USAGE_HIGH",
  "callbackUrl": "https://your-server.com/webhooks/gas-alerts"
}

Step 3: Handle Gas Usage Webhooks​

Your webhook endpoint will receive POST requests when gas usage is high.

GAS_USAGE_HIGH Webhook:

{
  "type": "GAS_USAGE_HIGH",
  "event": {
    "projectedUsage": 205248724363271500,
    "limit": 250000000000000000,
    "threshold": 80,
    "usagePercentage": 82.1,
    "remainingGas": 44751275636728500,
    "estimatedTransactions": 200,
    "timestamp": "2025-10-17T10:45:06.602Z"
  }
}

Event Fields:

  • projectedUsage: Current gas consumed (in wei)
  • limit: Your total gas limit (in wei)
  • threshold: Percentage that triggered alert (80%)
  • usagePercentage: Current usage as percentage
  • remainingGas: Gas remaining before limit
  • estimatedTransactions: Approximate transactions remaining
  • timestamp: Alert generation time

💡 Key Concepts​

Gas Limit Thresholds​

Warnings are triggered at different usage levels:

  • 80% Usage: First warning (webhook + response warnings)
  • 90% Usage: High priority warning
  • 95% Usage: Critical warning - contact support urgently
  • 100% Usage: Transactions will be rejected

Usage Reset​

Gas usage limits typically reset:

  • Monthly: On your billing cycle date
  • Custom: Per your agreement with Token City

Limit Increases​

To increase your gas limit:

  1. Contact Token City support
  2. Provide usage projections
  3. Upgrade to higher tier plan
  4. Custom enterprise agreements available

⚠️ Important Notes​

  1. Monitor Actively: Check response warnings on every transaction
  2. Set Up Webhooks: Subscribe to GAS_USAGE_HIGH for proactive alerts
  3. Plan Ahead: Request limit increases before reaching 90%
  4. Optimize Operations: Batch transactions when possible to reduce gas
  5. Emergency Contact: Have Token City support contact ready
  6. Transaction Rejection: At 100%, new transactions will fail

🔗 Related Endpoints​

🆘 Troubleshooting​

Not Receiving Gas Warnings​

If you're not seeing warnings:

  • ✓ Check response bodies for warnings array
  • ✓ Verify webhook subscription is active
  • ✓ Confirm webhook URL is accessible
  • ✓ Check you haven't exceeded 100% (transactions rejected)
  • ✓ Verify HMAC signature validation in webhook handler

High Gas Usage Unexpectedly​

If gas usage is higher than expected:

  • ✓ Review recent transaction history
  • ✓ Check for failed transactions (still consume gas)
  • ✓ Verify no unauthorized API access
  • ✓ Contact support for usage analysis

Transaction Rejected Due to Gas Limit​

If transactions are being rejected:

  • ✓ You've reached 100% of your gas limit
  • ✓ Request immediate limit increase from support
  • ✓ Wait for monthly reset (if applicable)
  • ✓ Prioritize critical transactions only
  • ✓ Review and optimize gas consumption

Webhook Not Triggered at 80%​

If webhook didn't fire at threshold:

  • ✓ Check webhook subscription includes GAS_USAGE_HIGH
  • ✓ Verify callback URL responds with 200 OK
  • ✓ Review webhook delivery logs in dashboard
  • ✓ Test webhook endpoint manually
  • ✓ Check for network/firewall issues

📚 Additional Resources​

💼 Use Case Examples​

Example 1: High-Volume Minting​

A platform is minting 1000 tokens and monitoring gas usage.

Setup:

{
  "event": "GAS_USAGE_HIGH",
  "callbackUrl": "https://platform.com/webhooks"
}

During Minting:

  • Transaction 800: Response shows 75% usage
  • Transaction 850: Response shows 82% usage + warning
  • Receive GAS_USAGE_HIGH webhook
  • Contact support to increase limit
  • Continue minting with higher limit

Result: Avoided service interruption by proactive monitoring.

Example 2: Monthly Usage Monitoring​

Company tracks gas usage throughout the month.

Week 1: 20% usage (50 transactions) Week 2: 45% usage (100 transactions) Week 3: 75% usage (150 transactions) Week 4: 85% usage + GAS_USAGE_HIGH webhook

Action Taken:

  • Optimized batch operations
  • Requested limit increase for next month
  • Completed month with 92% usage

Result: Smooth operations with planned scaling.

Example 3: Emergency Limit Increase​

Critical deployment day with unexpected gas consumption.

Morning: 60% usage Noon: 85% usage + HIGH warning Afternoon: 95% usage + CRITICAL warning

Response:

  1. Paused non-critical operations
  2. Contacted Token City support immediately
  3. Received emergency limit increase within 2 hours
  4. Completed critical deployment
  5. Set up better monitoring for future

Result: Successfully handled emergency with rapid support response.