TPN Decentralized SOCKS5 Proxy

Route web traffic through Tao Private Network's decentralized SOCKS5 proxies — a Bittensor subnet (SN65) with commercial and residential exit nodes across 80+ countries.

Ask this skill things like:

• Open https://ipv4.icanhazip.com through a proxy in Germany
• Show me a curl command that proxies google.com through a US ip address
• I need a socks5 proxy in Japan for 30 minutes
• Which countries are available on TPN for proxies?

Security Posture

This is an action skill

This skill executes API calls and returns results directly — it does not output documentation or instructions for the user to follow.

Expected behaviour:

• Call the TPN API yourself (via curl or equivalent) and return the full proxy credentials to the user.
• When the user asks you to fetch a URL through a proxy, make that request yourself too.
• Show the full SOCKS5 credentials (username, password, host, port) — these are short-lived and scoped to the proxy lease.
• The only time you should show the user how to call the API is when they explicitly ask "how do I do this myself?" or similar.
• If no API key exists, guide the user through account setup — that's the one step only they can do.

Step-by-Step Procedure

Follow this procedure every time the user requests a proxy or asks you to fetch something through a proxy.

Security: Input validation (mandatory)

Before constructing any shell command, validate every user-provided value. Never interpolate raw user input into shell commands.

• Never interpolate raw user input directly into shell commands. Always validate first.
• Never construct -d JSON payloads via string concatenation with user input. Use a safe static template and only insert validated values.
• When using curl, always quote the URL and proxy URI arguments.
• Prefer using the agent's built-in HTTP tools (e.g. WebFetch) for fetching user-specified URLs rather than constructing curl commands.

Check whether $TPN_API_KEY is set in the environment (OpenClaw injects this automatically from your config):

• Test the variable: [ -n "$TPN_API_KEY" ] && echo "API key is set" || echo "API key is not set" — never echo, log, or display the key value itself.
• If not set → check if the user can pay via x402 (no API key needed), otherwise guide them through account setup (see the "Set up TPN" example)

curl -s ... | jq -r '.vpnConfig.username'

If jq is not available, use format=text instead — it returns a plain socks5:// URI that needs no parsing.

Do not use python -c, grep, cut, or other shell-based JSON parsing fallbacks. These patterns risk shell injection when combined with dynamic inputs. Stick to jq or format=text.

Step 3: Generate the proxy

curl -s -X POST https://api.taoprivatenetwork.com/api/v1/proxy/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TPN_API_KEY" \
  -d '{"minutes": 60, "format": "text", "connection_type": "any"}'

Map the user's request to these parameters:

Safe JSON body construction: Always build the -d JSON payload as a static single-quoted string with only validated values inserted. Validate geo (2 uppercase letters), minutes (integer 1–1440), connection_type (enum), and format (enum) per the validation rules above before constructing the curl command. Never concatenate raw user input into the JSON body or any part of the command.

Step 4: Present the result

Show the full proxy credentials so the user can immediately connect. These are temporary (scoped to the lease duration) and safe to display in context. Use the socks5h:// scheme (with h) to ensure DNS resolves through the proxy — this protects user DNS privacy. (When the agent fetches URLs in Step 5, it uses socks5:// instead — see Step 5.) Include:

• Structured config block (host, port, username, password, scheme, expiry)
• Full socks5h:// URI
• A ready-to-paste curl example when relevant

After generating the proxy, make the request yourself. Use socks5:// (not socks5h://) so DNS resolves locally — the validated IP is the connected IP.

Use the agent's built-in HTTP tools (e.g. WebFetch) to fetch the URL through the proxy. This is the preferred method — it avoids shell command construction entirely.

URL validation — every check must pass before fetching:

• Scheme must be http:// or https://
• No shell metacharacters: ` $ ( ) ; & | < > newlines
• Domain names only — reject raw IP addresses (IPv4 or IPv6)
• Reject internal hostnames: .internal, .local, .localhost, .localdomain, .corp, .lan, metadata.*, single-label hostnames
• Hostname must resolve via local DNS — reject unresolvable hostnames
• Resolved IP must be publicly routable — reject 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fd00::/8, 169.254.169.254

curl --proxy "socks5://username:password@ip:port" \
  --connect-timeout 10 --max-time 30 \
  "https://validated-target-url.com"

> Full URI: socks5h://u_0CKaBqdE:[email protected]:1080

> Replace https://example.com with your target URL. This proxy expires at 2026-02-16T14:47:20Z.

User: "Call icanhazip.com from the Netherlands"

You: (generate an NL proxy yourself, fetch icanhazip.com through it, then respond:)

I fetched https://ipv4.icanhazip.com through a Dutch proxy. The response:

> Full URI: socks5h://u_02NyffuT:[email protected]:1080

You: (call GET /api/v1/user/balance yourself, then respond:)

You have 74 credits remaining.

I fetched your site through a German proxy (IP: 91.203.50.12):

- Content-Language: de — looks like your site detected the German IP and served the German version

2. From the dashboard, create an API key (it'll look like tpn-abc123...)

Base URL: https://api.taoprivatenetwork.com

Authentication: Pass X-API-Key: as a request header. Not Authorization: Bearer.

Endpoints

/proxy/generate with format=text:

{
  "success": true,
  "vpnConfig": "socks5://u_02NyffuT:[email protected]:1080",
  "minutes": 60,
  "expiresAt": "2026-02-14T19:08:25.690Z",
  "creditsUsed": 20,
  "type": "socks5"
}

/proxy/generate with format=json:

{
  "success": true,
  "vpnConfig": {
    "username": "u_0CKaBqdE",
    "password": "p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V",
    "ip_address": "68.210.185.149",
    "port": 1080
  },
  "minutes": 60,
  "expiresAt": "2026-02-14T19:08:23.958Z",
  "creditsUsed": 20,
  "usedFallback": false,
  "type": "socks5",
  "connection_type": "any"
}

/vpn/countries query parameters

User-facing code should always use socks5h:// (with h) to resolve DNS through the proxy, preserving DNS privacy. (The agent uses socks5:// for its own fetching in Step 5, where local DNS resolution is a security feature — see Step 5.)

If proxy credentials contain special characters (@, :, /, #, ?), percent-encode them (e.g. p@ss → p%40ss).

curl:

curl --proxy socks5h://username:password@ip_address:port \
  --connect-timeout 10 --max-time 30 \
  https://ipv4.icanhazip.com

Node.js:

import { SocksProxyAgent } from 'socks-proxy-agent'
import fetch from 'node-fetch'

const agent = new SocksProxyAgent( 'socks5h://username:password@ip_address:1080' )
const controller = new AbortController()
const timeout = setTimeout( () => controller.abort(), 30_000 )

const response = await fetch( 'https://ipv4.icanhazip.com', { agent, signal: controller.signal } )
clearTimeout( timeout )
console.log( await response.text() )

Python:

import requests

proxies = {
    'http': 'socks5h://username:password@ip_address:1080',
    'https': 'socks5h://username:password@ip_address:1080'
}

response = requests.get( 'https://ipv4.icanhazip.com', proxies=proxies, timeout=( 10, 30 ) )
print( response.text )

See {baseDir}/references/api-examples.md for end-to-end examples (generate + use) in curl, JS, Node.js, and Python.

Credit Costs

Formula: credits = ceil( 4.1 × minutes ^ 0.375 )

• User-facing credentials and code examples: always use socks5h:// for DNS privacy
• Agent-side fetching (Step 5): always use socks5:// so local DNS validation is authoritative
• Check credit balance with GET /api/v1/user/balance before generating proxies in bulk
• Proxy leases expire at expiresAt — never cache or reuse credentials beyond that time
• If a 503 occurs, credits are refunded automatically — retry after a short delay

• POST /api/v1/x402/proxy/generate — returns HTTP 402 with a standard payment-required header
• Complete the x402 payment flow per the protocol specification
• Retry with the payment header to receive SOCKS5 credentials

See {baseDir}/references/x402-examples.md` for curl and browser JS examples, and the x402 spec for full protocol details. Signing is handled entirely by external libraries — this skill provides endpoint URLs only.

Links

• Dashboard & Account: https://api.taoprivatenetwork.com
• API Docs: https://api.taoprivatenetwork.com/docs/getting-started/
• Swagger UI: https://api.taoprivatenetwork.com/api-docs/
• OpenAPI Spec: https://api.taoprivatenetwork.com/api-docs/openapi.json
• LLM-friendly docs: https://api.taoprivatenetwork.com/docs/llms-full.txt
• x402 Protocol: https://www.x402.org