BitTorrent Private Tracker Announce URL Structure

An announce request sent from a BitTorrent client to a private tracker is an HTTP or HTTPS GET request that communicates the client's current status and retrieves an updated list of peers. This article breaks down the anatomy of a private tracker announce URL, explaining how authentication tokens, transfer statistics, and identification parameters are formatted and transmitted.

The Anatomy of an Announce Request

A private tracker announce URL consists of the tracker's base endpoint, a user-specific authentication token, and a query string containing standard BitTorrent protocol parameters.

Example URL

https://tracker.example.com:443/announce?passkey=1a2b3c4d5e6f7g8h9i0j&info_hash=%ab%cd%ef%12%34%56%78%90%ab%cd%ef%12%34%56%78%90%ab%cd%ef%12&peer_id=-qB4520-1a2b3c4d5e6f&port=6881&uploaded=104857600&downloaded=524288000&left=0&compact=1&numwant=50&event=completed

1. Tracker Endpoint and Authentication

Unlike public trackers, private trackers must authenticate the user to credit upload and download statistics to the correct user account. This is handled via a passkey.

  • Path-based Passkey: https://tracker.example.com/announce/1a2b3c4d5e6f7g8h9i0j
  • Parameter-based Passkey: https://tracker.example.com/announce?passkey=1a2b3c4d5e6f7g8h9i0j

The passkey is a unique alphanumeric string tied directly to the user's account.

2. Core BitTorrent Query Parameters

The query string carries critical metadata regarding the specific torrent and the client's network status:

  • info_hash (20 bytes, URL-encoded):
    The 20-byte SHA-1 hash of the info dictionary from the torrent file. Binary characters are percent-encoded (e.g., %ab%cd%ef).

  • peer_id (20 bytes, URL-encoded):
    A unique identifier generated by the client upon startup to distinguish itself from other peers in the swarm. It often encodes the client name and version (e.g., -qB4520- for qBittorrent 4.5.2).

  • port (integer):
    The TCP/UDP port number that the client is listening on for incoming peer connections (e.g., 6881).

  • uploaded (integer, base 10):
    The total number of bytes uploaded for this torrent session since the started event was sent.

  • downloaded (integer, base 10):
    The total number of bytes downloaded for this torrent session since the started event was sent.

  • left (integer, base 10):
    The remaining number of bytes the client needs to download to complete the torrent. A value of 0 indicates that the client is currently seeding.

  • compact (integer, 0 or 1):
    Requests a compact peer list format. Setting compact=1 instructs the tracker to return peer IP addresses and ports as a dense binary string (6 bytes per IPv4 peer) instead of a dictionary format, saving bandwidth.

  • numwant (integer, optional):
    The number of peers the client wants to receive from the tracker. Defaults to 50 if omitted.

3. The event Parameter

The event parameter indicates state changes in the client. It is only included when a specific action occurs:

  • started: Sent when a download or seeding task begins or resumes.
  • completed: Sent when the download finishes and the client transitions from leeching (left > 0) to seeding (left=0).
  • stopped: Sent when the torrent is paused, stopped, or the client is shut down.
  • (omitted): When performing regular periodic interval updates, the event key is omitted entirely from the query string.

4. IP Identification (Optional)

  • ip (string, optional):
    The true external IP of the client. On private trackers, this is often ignored or heavily restricted to prevent spoofing, and the tracker relies instead on the source IP of the incoming TCP connection.
  • ipv4 / ipv6 (string, optional):
    Used in dual-stack environments where clients advertise distinct addresses for IPv4 and IPv6 connectivity.