Home > Specs > BitTorrent > Trackers
UDP Trackers

A UDP tracker announce is a very simple process.  First, a connection key is obtained.  The key is good for any number of announcements and is valid for one minute.  Then a single-packet request is sent, which is replied to with a single-packet response.


The connection key is obtained by sending a single UDP packet that starts with the following sequence:

0x04 0x17 0x27 0x10   0x19 0x80 0x00 0x00  0x00 0x00 0x00 0x00

This is followed by a randomly selected transaction ID that is 4 bytes long.  The total message length is 16 bytes.

The tracker response will start with the following sequence:

0x00 0x00 0x00 0x00

This is followed by the transaction ID (4 bytes) that was sent with the request, and then a connection key (8 bytes) that is used to make announcements in the next step.


The first 8 bytes of an announce request should be the connection key obtained in the last step.  This is followed by the sequence:

0x00 0x00 0x00 0x01

Next is another randomly selected transaction ID (4 bytes).

Then all the information specific to this torrent is added.  All numbers are big-endian.

Info Hash  20 bytes
This is the info hash of the torrent being announced.

Peer ID  20 bytes
This is the local peer ID for this torrent, which is also used for peer connection handshakes.

Bytes Downloaded  8-byte big-endian integer
If this is a STARTED event, this is zero, otherwise it's the number of bytes that have been downloaded in this torrent since the STARTED event.

Bytes Remaining  8-byte big-endian integer
This is the total byte size of the torrent minus the bytes that have been completed.

Bytes Uploaded  8-byte big-endian integer
If this is a STARTED event, this is zero, otherwise it's the number of bytes that have been uploaded in this torrent since the STARTED event.

Event Code  4-byte big-endian integer
Use 2 if we are announcing a STARTED event, which is always the first event we announce, even if the torrent is complete.  Use 1 to announce that a torrent that was already started has now completed.  Use 3 to announce that the torrent is no longer running.  Use 0 if none of the other codes apply and the announcement is just being refreshed.

IP Address  4 bytes
This should be set to all zeros.  It is not used.  The tracker already has the local address.  This is 4 bytes even if we are using IPv6.

Announce Key  4 bytes
If we are announcing a STARTED event, this should be a randomly generated string.  Otherwise, the string generated for the earlier STARTED event should be used.

Number Wanted  4 bytes big-endian integer
This is the number of peers that is desired in the response.  Set it to 100 unless we are making a STOPPED announcement, in which case it should be zero.  The tracker may send more or less than this number.

Port  2 bytes big-endian integer
This is the local incoming connection port.


The tracker will reply with a single UDP packet.

It will always begin with 0x00 0x00 0x00 0x01.

This is followed by the 4-byte transaction ID that we used in the announce message.

Next is a big-endian 4-byte integer that specifies the number of seconds to wait until refreshing the announce.

Then two big-endian 4-byte integers that specify the number of incomplete and complete peers that the tracker knows about for this torrent.

The rest of the message is a compact representation of all the peer addresses the tracker is returning.  If we are contacting this tracker over IPv4, then each address will be 4 bytes for the IP followed by 2 bytes for the port.  If IPv6, then 16 bytes for the IP followed by 2 for the port.