diff --git a/docs/payloads.md b/docs/payloads.md
new file mode 100644
index 000000000..2c4021022
--- /dev/null
+++ b/docs/payloads.md
@@ -0,0 +1,176 @@
+# Meshcore payloads
+Inside of each [meshcore packet](./packet_structure.md) is a payload, identified by the payload type in the packet header. The types of payloads are:
+
+* Request (destination/source hashes + MAC).
+* Response to REQ or ANON_REQ.
+* Plain text message.
+* Acknowledgment.
+* Node advertisement.
+* Group text message (unverified).
+* Group datagram (unverified).
+* Anonymous request.
+* Returned path.
+* Custom packet (raw bytes, custom encryption).
+
+This document defines the structure of each of these payload types
+
+# Node advertisement
+This kind of payload notifies receivers that a node exists, and gives information about the node
+
+| Field         | Size (bytes)    | Description                                              |
+|---------------|-----------------|----------------------------------------------------------|
+| public key    | 32              | Ed25519 public key                                       |
+| timestamp     | 4               | unix timestamp of advertisement                          |
+| signature     | 64              | Ed25519 signature of public key, timestamp, and app data |
+| appdata       | rest of payload | optional, see below                                      |
+
+Appdata
+
+| Field         | Size (bytes)    | Description                                           |
+|---------------|-----------------|-------------------------------------------------------|
+| flags         | 1               | specifies which of the fields are present, see below  |
+| latitude      | 4               | decimal latitude multiplied by 1000000, integer       |
+| longitude     | 4               | decimal longitude multiplied by 1000000, integer      |
+| feature 1     | 2               | reserved for future use                               |
+| feature 2     | 2               | reserved for future use                               |
+| name          | rest of appdata | name of the node                                      |
+
+Appdata Flags
+
+| Value  | Name      | Description                           |
+|--------|-----------|---------------------------------------|
+| `0x10` | location  | appdata contains lat/long information |
+| `0x20` | feature 1 | Reserved for future use.              |
+| `0x40` | feature 2 | Reserved for future use.              |
+| `0x80` | name      | appdata contains a node name          |
+
+# Acknowledgement
+| Field    | Size (bytes) | Description                                                |
+|----------|--------------|------------------------------------------------------------|
+| checksum | 4            | CRC checksum of message timestamp, text, and sender pubkey |
+
+
+# Returned path, request, response, and plain text message
+| Field            | Size (bytes)    | Description                                          |
+|------------------|-----------------|------------------------------------------------------|
+| destination hash | 1               | first byte of destination node public key            |
+| source hash      | 1               | first byte of source node public key                 |
+| cipher MAC       | 2               | MAC for encrypted data in next field                 |
+| ciphertext       | rest of payload | encrypted message, see subsections below for details |
+
+## Returned path
+
+| Field       | Size (bytes) | Description                                                                                  |
+|-------------|--------------|----------------------------------------------------------------------------------------------|
+| path length | 1            | length of next field                                                                         |
+| path        | see above    | a list of node hashes (one byte each) describing the route from us to the packet author      |
+| extra type  | 1            | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec     |
+| extra       | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
+
+## Request
+
+| Field        | Size (bytes)    | Description                |
+|--------------|-----------------|----------------------------|
+| timestamp    | 4               | send time (unix timestamp) |
+| request type | 1               | see below                  |
+| request data | rest of payload | depends on request type    |
+
+Request type
+
+| Value  | Name               | Description                           |
+|--------|--------------------|---------------------------------------|
+| `0x01` | get status         | get status of repeater or room server |
+| `0x02` | keepalive          | TODO |
+| `0x03` | get telemetry data | TODO |
+
+### Get status
+
+Gets information about the node, possibly including the following:
+
+* Battery level (millivolts)
+* Current transmit queue length
+* Current free queue length
+* Last RSSI value
+* Number of received packets
+* Number of sent packets
+* Total airtime (seconds)
+* Total uptime (seconds)
+* Number of packets sent as flood
+* Number of packets sent directly
+* Number of packets received as flood
+* Number of packets received directly
+* Error flags
+* Last SNR value
+* Number of direct route duplicates
+* Number of flood route duplicates
+* Number posted (?)
+* Number of post pushes (?)
+
+### Keepalive
+
+No-op request.
+
+### Get telemetry data
+
+Request data about sensors on the node, including battery level.
+
+## Response
+
+| Field   | Size (bytes)    | Description |
+|---------|-----------------|-------------|
+| tag     | 4               | TODO        |
+| content | rest of payload | TODO        |
+
+## Plain text message
+
+| Field        | Size (bytes)    | Description                                                  |
+|--------------|-----------------|--------------------------------------------------------------|
+| timestamp    | 4               | send time (unix timestamp)                                   |
+| flags + TODO | 1               | first six bits are flags (see below), last two bits are TODO |
+| message      | rest of payload | the message content, see next table                          |
+
+Flags
+
+| Value  | Description               | Message content                                            |
+|--------|---------------------------|------------------------------------------------------------|
+| `0x00` | plain text message        | the plain text of the message                              |
+| `0x01` | CLI command               | the command text of the message                            |
+| `0x02` | signed plain text message | two bytes of sender prefix, followed by plain text message |
+
+# Anonymous request
+
+| Field            | Size (bytes)    | Description                               |
+|------------------|-----------------|-------------------------------------------|
+| destination hash | 1               | first byte of destination node public key |
+| public key       | 32              | sender's Ed25519 public key               |
+| cipher MAC       | 2               | MAC for encrypted data in next field      |
+| ciphertext       | rest of payload | encrypted message, see below for details  |
+
+Plaintext message
+
+| Field          | Size (bytes)    | Description                                                                   |
+|----------------|-----------------|-------------------------------------------------------------------------------|
+| timestamp      | 4               | send time (unix timestamp)                                                    |
+| sync timestamp | 4               | for room server, otherwise absent: sender's "sync messages SINCE x" timestamp |
+| password       | rest of message | password for repeater/room                                                    |
+
+# Group text message / datagram
+
+| Field        | Size (bytes)    | Description                              |
+|--------------|-----------------|------------------------------------------|
+| channel hash | 1               | TODO                                     | 
+| cipher MAC   | 2               | MAC for encrypted data in next field     |
+| ciphertext   | rest of payload | encrypted message, see below for details |
+
+Plaintext for text message
+
+| Field     | Size (bytes)    | Description                      |
+|-----------|-----------------|----------------------------------|
+| timestamp | 4               | send time (unix timestamp)       |
+| content   | rest of message | plain group text message content |
+
+TODO: describe what datagram looks like
+
+# Custom packet
+
+Custom packets have no defined format.
\ No newline at end of file