Trick-or-Treat Protocol (TTP/1.0) API Reference

Introduction

The Trick-or-Treat Protocol has operated as an informal, undocumented standard for centuries, leading to countless implementation inconsistencies, edge-case failures, and interoperability nightmares across residential networks. Children arrive at doorsteps with wildly varying expectations. Homeowners deploy candy distribution systems with no regard for standardized response formats. The result is chaos: double-dipping, premature bowl depletion, authentication failures, and the dreaded silent timeout when a homeowner simply refuses to answer the door.

This specification formalizes the timeless Trick-or-Treat Protocol as a stateless, request-response API that can be implemented consistently across all residential nodes in a neighborhood network. By adhering to TTP/1.0, we can ensure reliable candy acquisition, predictable error handling, and a delightful user experience for all stakeholders.

This document is intended for implementers on both sides of the transaction: Requesters (trick-or-treaters) and Responders (candy distributors). Compliance with this specification is REQUIRED for participation in Halloween 2025 and beyond.

Protocol Overview

The Trick-or-Treat Protocol operates on a simple request-response model over a physical transport layer (sidewalk/driveway). Each transaction follows this sequence:

1. Discovery: Requester identifies an available endpoint (house with porch light on)
2. Connection: Requester traverses the pathway to the front door
3. Authentication: Requester presents credentials (costume)
4. Request: Requester invokes the standard greeting
5. Response: Responder returns candy payload
6. Termination: Requester acknowledges and disconnects

Base URL

Each residential endpoint exposes its API at:

physical://[street-address]/front-door

Example:

physical://123-maple-street/front-door

Alternative endpoints such as side-door or garage are considered non-standard and SHOULD NOT be used except in cases of explicit signage indicating a redirect.

Authentication

Costume-Based Authentication

All requests MUST include valid costume credentials. The costume serves as a bearer token that grants access to the candy distribution endpoint.

Valid Costume Criteria:

• MUST cover at least 40% of the requester's body
• MUST be thematically appropriate (Halloween, horror, pop culture, or whimsical)
• MUST be worn with commitment (half-hearted attempts MAY result in reduced payload)

Invalid Credentials:

• Regular street clothes with no modifications
• A t-shirt that says "This is my costume"
• Costumes worn inside-out or backwards (unless intentionally part of the concept)

Authentication Failures:

If authentication fails, the responder MAY return a 401 Unauthorized response (verbal reprimand) or a 403 Forbidden response (door closed without candy).

Age-Based Access Control

While not strictly enforced in the protocol, many responders implement age-based access control policies. Requesters over the age of 14 are considered edge cases and MAY receive:

• Reduced payloads
• Judgmental looks
• Lectures about "being too old for this"

Implementers are encouraged to be lenient with edge cases, as the protocol benefits from maximum participation.

Endpoints

POST /front-door/trick-or-treat

Initiates a candy acquisition request.

Request Format

Transport Method: Auditory (spoken aloud)

Required Payload:

"Trick or treat!"

Optional Enhancements:

• "Smell my feet!" (deprecated but still supported for backwards compatibility)
• "Give me something good to eat!" (verbose mode)
• Singing or performing a joke (premium tier request)

Headers:

The request MUST include the following implicit headers:

• Costume-Type: String describing the costume (e.g., "ghost", "vampire", "influencer")
• Group-Size: Integer representing the number of requesters in the party
• Politeness-Level: Integer from 1-10, inferred from tone and body language
• Bag-Capacity-Remaining: Float representing available storage (0.0 = full, 1.0 = empty)

Response Format

Success Response (200 OK):

The responder returns a candy payload. The payload structure is highly variable and depends on the responder's inventory and generosity settings.

Response Body:

{
  "status": "success",
  "candy": [
    {
      "type": "chocolate_bar",
      "brand": "Snickers",
      "size": "fun",
      "quantity": 1
    }
  ],
  "message": "Happy Halloween!"
}

Possible Candy Types:

• chocolate_bar (high value)
• hard_candy (medium value)
• gummy (medium value)
• lollipop (low value)
• raisin_box (negative value, considered a protocol violation)
• toothbrush (error condition, see below)

Size Modifiers:

• king: Premium size, rare
• full: Standard retail size, uncommon
• fun: Miniature size, most common
• bite: Microscopic size, borderline insulting

Error Responses:

404 Not Found

{
  "status": "error",
  "code": 404,
  "message": "No one home",
  "details": "Porch light is off. Endpoint is unavailable."
}

429 Too Many Requests

{
  "status": "error",
  "code": 429,
  "message": "You were just here",
  "retry_after": 3600,
  "details": "Rate limit exceeded. Try a different house."
}

503 Service Unavailable

{
  "status": "error",
  "code": 503,
  "message": "Out of candy",
  "details": "Inventory depleted. Endpoint is closed for the evening."
}

400 Bad Request

{
  "status": "error",
  "code": 400,
  "message": "Invalid costume",
  "details": "Authentication failed. Costume does not meet minimum requirements."
}

451 Unavailable for Legal Reasons

{
  "status": "error",
  "code": 451,
  "message": "Parents said no more sugar",
  "details": "Request blocked by parental controls."
}

Response Headers

Set-Cookie: If the responder is particularly generous, they may set a cookie (literally) that grants the requester permission to return next year.

X-Homeowner-Mood: String indicating the responder's current disposition (cheerful, tired, overwhelmed, regrets_answering_door)

X-Bowl-Strategy: Enum indicating candy distribution strategy (one_per_child, handful, honor_system, full_bars_only)

Rate Limiting

Requesters MUST NOT invoke the same endpoint more than once per evening. Responders implement sophisticated rate limiting using facial recognition, costume recognition, or simply remembering "that kid who was just here five minutes ago."

Rate Limit Headers:

• X-RateLimit-Limit: 1
• X-RateLimit-Remaining: 0 (after first request)
• X-RateLimit-Reset: 31536000 (seconds until next Halloween)

Violating rate limits may result in:

• Public shaming
• Reduced payload on subsequent requests
• Permanent ban from the endpoint

Special Endpoints

GET /front-door/status

Check if the endpoint is currently accepting requests.

Request:

Look at the porch light

Response:

•200 OK: Light is on, endpoint is active

•404 Not Found: Light is off, endpoint is unavailable

This is a read-only operation and does not consume rate limit quota.

POST /front-door/trick

An alternative, rarely-invoked endpoint. If the requester chooses "trick" instead of "treat," the responder is obligated to perform a prank or joke.

Warning: This endpoint is deprecated and considered dangerous. Most responders do not implement it correctly, leading to undefined behavior. Use at your own risk.

Known Responses:

• Dad jokes
• Awkward magic tricks
• Being sprayed with silly string
• 501 Not Implemented (most common)

Query Parameters

?group=true

Indicates that the request is being made on behalf of a group. Responders SHOULD increase the payload quantity proportionally.

Example:

POST /front-door/trick-or-treat?group=true

?allergy=peanut

Indicates a dietary restriction. Responders with advanced inventory management systems MAY filter the response accordingly.

Supported Values:

• peanut
• gluten
• dairy
• fun (for children who only accept the most boring candy)

‍

Example:

POST /front-door/trick-or-treat?allergy=peanut

Response:

{
  "status": "success",
  "candy": [
    {
      "type": "gummy",
      "brand": "Haribo",
      "allergen_free": true
    }
  ]
}

‍

Edge Cases and Undefined Behavior

The Honor System Bowl

Some endpoints deploy an unattended candy bowl with a sign reading "Take One." This represents a shift from a request-response model to a self-service model with optimistic concurrency control.

Expected Behavior:

Take one piece of candy

Actual Behavior:

Take one handful of candy, or empty the entire bowl if no one is watching

This is a known vulnerability in the protocol. The honor system bowl suffers from:

• Byzantine fault tolerance issues: Malicious actors may take more than their share
• Lack of authentication: No verification that the requester is authorized
• Inventory depletion: First requesters may exhaust the supply, causing 503 errors for subsequent requesters

Recommendation: Implementers should avoid the honor system bowl unless they have implemented advanced monitoring (doorbell camera, motion sensors, neighborhood watch).

The "Just Leave It on the Porch" Pattern

In recent years, some responders have adopted a contactless distribution model, leaving pre-bagged candy on the porch. This is equivalent to a static file server rather than a dynamic API.

Pros:

• No authentication required
• No wait time
• Socially distanced

Cons:

• No personalization
• Higher risk of inventory depletion
• Reduced human interaction (defeats the spirit of the protocol)

The Full-Size Candy Bar House

A legendary endpoint that returns king or full size candy. These endpoints experience extreme traffic and may suffer from:

• DDoS conditions: Overwhelming number of requesters
• Queue exhaustion: Long lines extending into the street
• Reputation propagation: Word spreads quickly, attracting requesters from outside the local network

Responders who deploy full-size candy bars should implement queue management, load balancing, and prepare for sustained high traffic.

The "We're Out" Sign

A manually deployed 503 response. Responders who exhaust their inventory often place a sign on the door indicating unavailability. This is considered best practice and prevents unnecessary connection attempts.

The Teenager Dilemma

Requesters aged 13-17 represent a gray area in the protocol. They are technically valid requesters but may be subject to additional scrutiny. Responders often implement heuristic-based evaluation:

• High-effort costume + polite demeanor = Full payload
• Low-effort costume + entitled attitude = Reduced payload or 400 Bad Request

The Parent Tax

Parents accompanying young requesters often expect a share of the payload. This is not part of the official specification but is widely practiced. Some responders include adult-oriented candy (dark chocolate, premium brands) specifically for this purpose.

Implementation Note: The parent tax is an implicit feature and should not be explicitly documented in the response payload.

The Pet in Costume

Some requesters attempt to authenticate using a pet in costume. This is a novel edge case with no standardized response. Responders typically:

• Award candy to the pet's owner
• Take excessive photographs
• Provide dog treats if available (non-standard payload type)

Security Considerations

Stranger Danger Mitigation

The protocol inherently involves interaction between strangers, which presents security risks. Both requesters and responders should implement safety measures:

Requesters:

• Travel in groups
• Stay in well-lit areas
• Avoid endpoints that appear suspicious (no lights, overgrown yard, ominous decorations that seem too realistic)

Responders:‍

• Keep interactions brief and professional
• Do not invite requesters inside (protocol violation)
• Ensure adequate lighting to prevent trip hazards

Candy Tampering

All candy payloads should be inspected before consumption. Requesters should discard:

• Unwrapped candy
• Homemade items from unknown responders
• Anything that looks suspicious

Responders should only distribute factory-sealed candy to avoid liability and maintain trust in the protocol.

Privacy

Responders should not collect personally identifiable information (PII) from requesters beyond what is necessary to complete the transaction. Doorbell cameras and other monitoring devices should comply with local privacy regulations.

Best Practices

For Requesters

1. Start early: Popular endpoints may run out of inventory
2. Be polite: A high Politeness-Level header increases payload quality
3. Optimize your route: Plan an efficient path through the neighborhood to maximize candy acquisition
4. Bring adequate storage: Ensure your bag has sufficient Bag-Capacity-Remaining
5. Say thank you: Always acknowledge the response, even if the payload is suboptimal (e.g., raisins)

For Responders

1. Stock up: Ensure adequate inventory to handle expected traffic
2. Turn on the porch light: This is the universal signal that your endpoint is active
3. Be generous: The protocol thrives on goodwill
4. Have a backup plan: Keep extra candy in reserve for late-arriving requesters
5. Enjoy the experience: This is a once-a-year event; embrace the chaos

Versioning

This document describes TTP/1.0, the first formalized version of the Trick-or-Treat Protocol. Future versions may include:

• TTP/1.1: Enhanced support for dietary restrictions and allergen filtering
• TTP/2.0: Contactless distribution with QR code-based candy redemption
• TTP/3.0: Blockchain-based candy tracking to prevent double-dipping

Conclusion

The Trick-or-Treat Protocol is a time-honored tradition that, when properly implemented, brings joy to millions of requesters and responders each year. By adhering to this specification, we can reduce errors, improve interoperability, and ensure that Halloween remains a delightful, candy-filled experience for all participants.

May your endpoints be plentiful, your payloads generous, and your rate limits never exceeded.

Happy Halloween, and happy coding.

Appendix A: Sample Implementation (Python)

class TrickOrTreatAPI:
    def __init__(self, candy_inventory, porch_light_on=True):
        self.candy_inventory = candy_inventory
        self.porch_light_on = porch_light_on
        self.visitors = set()
    
    def get_status(self):
        """GET /front-door/status"""
        if self.porch_light_on and len(self.candy_inventory) > 0:
            return {"status": "available", "code": 200}
        return {"status": "unavailable", "code": 404}
    
    def post_trick_or_treat(self, requester_id, costume, politeness_level):
        """POST /front-door/trick-or-treat"""
        
        # Check if endpoint is available
        if not self.porch_light_on:
            return {"status": "error", "code": 404, "message": "No one home"}
        
        # Check inventory
        if len(self.candy_inventory) == 0:
            return {"status": "error", "code": 503, "message": "Out of candy"}
        
        # Rate limiting
        if requester_id in self.visitors:
            return {"status": "error", "code": 429, "message": "You were just here"}
        
        # Authentication
        if not costume or costume == "regular clothes":
            return {"status": "error", "code": 400, "message": "Invalid costume"}
        
        # Successful response
        self.visitors.add(requester_id)
        candy = self.candy_inventory.pop()
        
        return {
            "status": "success",
            "code": 200,
            "candy": [candy],
            "message": "Happy Halloween!"
        }

# Example usage
api = TrickOrTreatAPI(
    candy_inventory=[
        {"type": "chocolate_bar", "brand": "Snickers", "size": "fun"},
        {"type": "chocolate_bar", "brand": "Reese's", "size": "fun"},
        {"type": "hard_candy", "brand": "Jolly Rancher", "size": "bite"}
    ],
    porch_light_on=True
)

# Requester arrives
response = api.post_trick_or_treat(
    requester_id="kid_123",
    costume="vampire",
    politeness_level=9
)
print(response)
# Output: {'status': 'success', 'code': 200, 'candy': [{'type': 'hard_candy', 'brand': 'Jolly Rancher', 'size': 'bite'}], 'message': 'Happy Halloween!'}

Appendix B: Common Error Messages

Appendix C: Candy Value Matrix

For implementers who need to calculate fair payload distribution:

‍

Document Version: 1.0.0
Last Updated: October 2025
Maintained by: The Internet Engineering Trick-or-Treat Force (IETTF)