Cheshire API Documentation

Base URL
https://cheshire.liddell.cloud/api/v1/
Production
ℹ️ URLs subject to change

Authentication

All API requests must be authenticated using your API key. The key should be included in the request headers.

Required Headers

{
'key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}

API Key Security

  • Keep your API key secure and never share it publicly
  • Use environment variables to store your API key
  • Each API key has rate limiting applied
⚠️ Security Notice

Never expose your API key in client-side code or public repositories. Always make API calls from your server-side application.

API Endpoints

POST /invoice
Requires Auth Rate Limited

Create Invoice

Creates a new payment invoice with customizable parameters and webhook notifications.

Request Parameters

Parameter Type Required Description
send_to string Required Valid Cheshire account username
invoice_name string Required Name/title of the invoice
invoice_amount integer Required Amount in shards (1 shard = 1¢)
expiration integer Required Expiration time in minutes
callback_url string Optional* Webhook URL for payment notifications
disc_webhook string Optional* Discord webhook URL for notifications
* Either callback_url or disc_webhook must be provided

Response Parameters

Parameter Type Description
expires_at string ISO 8601 timestamp of invoice expiration
invoice_id string Unique UUID for the created invoice
message string Success or error message

Status Codes

Code Description
201 Invoice created successfully
400 Invalid request parameters
401 Invalid or missing API key
500 Server sided error
POST /invfee
Requires Auth Rate Limited

Get Invoice Fee Details

Retrieve detailed fee information and transfer ability for a specific invoice.

Request Parameters

Parameter Type Required Description
disc_id string Required Discord ID of the user who wants to pay
invoice_id string Required UUID of the invoice from /invoice response

Response Parameters

Parameter Type Description
after_fee integer Transfer cost after fee application
balance_after integer User's remaining balance after transfer
fee integer Fee amount for the transfer
fee_percent integer Fee percentage applied
invoice_amount integer Original invoice amount
invoice_name string Name of the invoice
invoice_reason string Reason for the invoice
send_to string Username of the recipient

Status Codes

Code Description
200 Fee details retrieved successfully
400 Invalid request parameters
401 Invalid or missing API key
404 Invoice not found
500 Server sided error

API Callbacks

Callback Overview

When you supply a callback URL in your invoice creation, you'll receive a POST request to that URL when the invoice is fulfilled. Here's what you need to know about handling callbacks.

Implementation Tips

  • Use Flask for discord.py implementations
  • Use Express for discord.js implementations
  • Always verify callback authenticity using the verify_hash

Callback Response Format

Parameter Type Description
invoice_id string Unique identifier for the invoice
transfer_id string Unique identifier for the transfer
fulfilled_by string Username of who fulfilled the invoice
invoice_name string Name of the invoice
invoice_reason string Reason for the invoice
invoice_amount integer Amount of the invoice in shards
fulfilled_timestamp string ISO 8601 timestamp of when the invoice was fulfilled
time string Current ISO 8601 timestamp
verify_hash string Hash for verifying callback authenticity
🔐

Verifying Callbacks

Ensure the authenticity of callbacks by following our secure verification process

Step 1
🔑 Gather Required Data
  • Extract transfer_id from callback
  • Get your API key from config
  • Note the received verify_hash
Step 2
🔄 Create HMAC
  • Use SHA512 algorithm
  • API key as HMAC key
  • transfer_id as message
Step 3
📋 Encode Result
  • Take HMAC output
  • Encode using Base64
  • Use standard Base64 encoding
Step 4
✅ Verify Match
  • Compare encoded HMAC
  • Match against verify_hash
  • Accept or reject request
📝 Implementation Note

Always use secure cryptographic libraries for HMAC generation and comparison. Avoid implementing these security-critical functions yourself.

🔒 Security Tip

Please implement callback verification in case your endpoint is leaked

⚡ Performance Tip

Verify the hash before processing any callback data

💡 Implementation Tip

Store API keys securely in environment variables

Error Codes

Code Description Resolution
ERR001 Invalid request payload Check your request payload format and required fields
ERR002 Cannot transfer to the same account Use different accounts for sender and receiver
ERR005 From user is banned Contact support for account status
ERR007 To user not found Verify the recipient username exists
ERR008 To user OTP not verified Recipient must verify their OTP first
ERR009 Insufficient balance The user has insufficient balance for the transaction
ERR031 Value must be a non-negative integer Check numeric field values in payload
ERR034 Critical unknown error Contact support with request/response details
ERR046 Missing callback URL or Discord webhook Provide either callback_url or disc_webhook
ERR048 Invoice not found Verify the invoice ID exists