# ⚠️ 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
- [Swagger UI Token City Blockchain API](../api-1.8.1/blockchain-api-token-city)
---
## ✨ 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:**
```json
{
"to": "0x1234567890abcdef1234567890abcdef12345678",
"amount": "1000000000000000000"
}
```
**Response with Warning:**
```json
{
"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:**
```json
{
"eventTypes": ["GAS_USAGE_HIGH"],
"callbackUrl": "https://your-server.com/webhooks/gas-alerts",
"filterByClient": true
}
```
**Response:**
```json
{
"subscriptionId": "sub_456e7890-e89b-12d3-a456-426614174111",
"eventTypes": ["GAS_USAGE_HIGH"],
"callbackUrl": "https://your-server.com/webhooks/gas-alerts",
"active": true,
"createdAt": "2025-11-10T10:30:00Z"
}
```
---
### Step 3: Handle Gas Usage Webhooks
Your webhook endpoint will receive POST requests when gas usage is high.
**GAS_USAGE_HIGH Webhook:**
```json
{
"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
7. **No Retroactive**: Warnings don't refund or reverse transactions
---
## 🔗 Related Endpoints
- [Subscribe to Webhooks](../api-1.8.1/create-webhook-subscription)
- [Mint Token](../api-1.8.1/mints-into-an-account)
- [Transfer Token](../api-1.8.1/executing-transfer-on-erc-20-token)
- [Burn Token](../api-1.8.1/burns-from-an-account)
---
## 🆘 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
- ✓ Look for inefficient transaction patterns
- ✓ 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
- [HMAC Authentication Guide](./hmac-authentication)
- [Webhook Notification Guide](./send-transaction-and-receive-status-via-webhook)
- [Ethereum Gas Explained](https://ethereum.org/en/developers/docs/gas/)
- [Token City Support](mailto:[email protected])
---
## 💼 Use Case Examples
### Example 1: High-Volume Minting
A platform is minting 1000 tokens and monitoring gas usage.
**Setup:**
```json
{
"eventTypes": ["GAS_USAGE_HIGH", "TX_MINED", "TX_FAILED"],
"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:**
- Reviewed usage patterns
- 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.