> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roundproxies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UDP over SOCKS5

> Send UDP traffic such as DNS, QUIC, games and VoIP through residential proxies.

Residential proxies can carry UDP as well as TCP when you connect over SOCKS5. Your client opens a normal SOCKS5 connection, asks for a UDP relay, and then sends its UDP packets to that relay. We forward them to the destination and send the replies back the same way.

<Note>
  You need a SOCKS5 client that supports the **`UDP ASSOCIATE`** command. Many tools, `curl` for example, only send TCP over SOCKS5. They can log in but can't send UDP.
</Note>

## Connection Settings

| Setting | Value |
| - | - |
| Protocol | SOCKS5 |
| Host | `residential.roundproxies.com` |
| Port | `5002` for sticky sessions or `5001` for rotating IPs. Both support UDP. |
| Username | Your normal username with `-udp-true` added |
| Password | Your normal password |

```
socks5://client-{CLIENT_ID}-country-UnitedStates-udp-true:{PASSWORD}@residential.roundproxies.com:5002
```

<ResponseField name="udp" type="string" required="false">
  `true` to route the session over the UDP-capable path. `1`, `yes` and `on` also work.
</ResponseField>

You can combine `udp-true` with [geo-targeting](/residentials/geo-targeting), [OS-targeting](/residentials/os-targeting), [location fallback](/residentials/location-fallback) and [sessions](/residentials/session). Put it before the session ID:

```
client-{CLIENT_ID}-country-UnitedStates-udp-true-session-{SESSION_ID}
```

<Tip>
  UDP also works without `udp-true`. Adding it sends your TCP connections over the same path, so the TCP and UDP traffic of a sticky session share one identity. Add it whenever you use both.
</Tip>

## How It Works

1. Your client opens a SOCKS5 connection to `residential.roundproxies.com:5002` and logs in.
2. It sends a `UDP ASSOCIATE` request.
3. We reply with the address and port of your UDP relay.
4. Your client sends its UDP packets to the relay, and we forward them to the destination.
5. Replies come back through the relay.

Keep the connection from step 1 open while you use UDP. Closing it ends the relay.

## Test With a DNS Query

DNS runs over UDP port `53`, so it is the quickest way to test. This example uses [PySocks](https://pypi.org/project/PySocks/) (`pip install pysocks`) to look up `example.com` at `1.1.1.1`:

```python Python theme={null}
import random
import socket
import struct

import socks  # pip install pysocks


def dns_query(name):
    header = struct.pack('>HHHHHH', random.randint(0, 0xFFFF), 0x0100, 1, 0, 0, 0)
    qname = b''.join(bytes([len(p)]) + p.encode() for p in name.split('.')) + b'\x00'
    return header + qname + struct.pack('>HH', 1, 1)  # type A, class IN


s = socks.socksocket(socket.AF_INET, socket.SOCK_DGRAM)
s.set_proxy(socks.SOCKS5, 'residential.roundproxies.com', 5002,
            username='client-{CLIENT_ID}-udp-true', password='{PASSWORD}')
s.settimeout(10)

s.sendto(dns_query('example.com'), ('1.1.1.1', 53))
reply, _ = s.recvfrom(4096)
answers = struct.unpack('>H', reply[6:8])[0]
print(f'UDP over SOCKS5 is working: {answers} answer(s) for example.com')
```

If you get a DNS answer back, UDP is working.

## Rules and Limits

* **Same IP for TCP and UDP.** Your UDP packets must come from the same public IP as your SOCKS5 login. Packets from other IPs are dropped. The first packet also fixes the UDP port you send from.
* **Blocked ports.** Mail (SMTP, POP3, IMAP), FTP, SSH and Telnet ports are blocked, the same as for TCP. Packets to them are dropped.
* **No fragmentation.** SOCKS5 UDP fragments are not supported. Each packet has to fit in one UDP datagram.
* **Billing.** UDP packets in both directions count toward your data balance, the same as TCP. When your balance runs out, the relay closes.

## Troubleshooting

| Problem | Cause | Fix |
| - | - | - |
| Login fails (SOCKS5 auth status `1`) | Wrong credentials, or no data left. | Check your username, password and balance in the [dashboard](https://app.roundproxies.com/dashboard/residential). |
| `UDP ASSOCIATE` fails or "command not supported" | Your client doesn't support UDP, or isn't using SOCKS5. | Use a SOCKS5 client that supports `UDP ASSOCIATE`, on port `5001` or `5002`. |
| `UDP ASSOCIATE` works but no reply arrives | Packets aren't reaching the relay, or replies aren't reaching you. | Check that your firewall allows UDP in and out, that UDP leaves from the same IP as your login, and that the SOCKS5 connection is still open. |
| Relay stops during a session | The SOCKS5 connection closed, or your data ran out. | Keep the connection open and check your balance. |

If `UDP ASSOCIATE` fails, you get the same SOCKS5 reply codes as for a failed TCP connection. See [Error Handling](/residentials/error-handling).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.