{ "schemaVersion": "1.0", "item": { "slug": "tpn-proxy", "name": "TPN Proxy", "source": "tencent", "type": "skill", "category": "通讯协作", "sourceUrl": "https://clawhub.ai/actuallymentor/tpn-proxy", "canonicalUrl": "https://clawhub.ai/actuallymentor/tpn-proxy", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/tpn-proxy", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tpn-proxy", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "references/api-examples.md", "references/security-assessment.md", "references/x402-examples.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/tpn-proxy" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/tpn-proxy", "agentPageUrl": "https://openagent3.xyz/skills/tpn-proxy/agent", "manifestUrl": "https://openagent3.xyz/skills/tpn-proxy/agent.json", "briefUrl": "https://openagent3.xyz/skills/tpn-proxy/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "TPN Decentralized SOCKS5 Proxy", "body": "Route web traffic through Tao Private Network's decentralized SOCKS5 proxies — a Bittensor subnet (SN65) with commercial and residential exit nodes across 80+ countries.\n\nAsk this skill things like:\n\nOpen https://ipv4.icanhazip.com through a proxy in Germany\nShow me a curl command that proxies google.com through a US ip address\nI need a socks5 proxy in Japan for 30 minutes\nWhich countries are available on TPN for proxies?" }, { "title": "Security Posture", "body": "AspectDetailEnvironment variablesTPN_API_KEY — existence-checked only ([ -n \"$TPN_API_KEY\" ]), never echoed or loggedFiles read/writtenNoneOther secrets accessedNone — no signing keys, no credentials beyond TPN_API_KEYNetwork destinationsapi.taoprivatenetwork.com (API calls) + user-specified URLs (validated per Step 5)x402 signingHandled entirely by external libraries (@x402/*); this skill provides endpoint URLs only" }, { "title": "This is an action skill", "body": "This skill executes API calls and returns results directly — it does not output documentation or instructions for the user to follow.\n\nExpected behaviour:\n\nCall the TPN API yourself (via curl or equivalent) and return the full proxy credentials to the user.\nWhen the user asks you to fetch a URL through a proxy, make that request yourself too.\nShow the full SOCKS5 credentials (username, password, host, port) — these are short-lived and scoped to the proxy lease.\nThe 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.\nIf no API key exists, guide the user through account setup — that's the one step only they can do.\n\nA good check: if your response contains \"you can run this command to…\" or \"use this curl to generate…\", reconsider — the user invoked this skill expecting you to run the command and hand them the output." }, { "title": "Step-by-Step Procedure", "body": "Follow this procedure every time the user requests a proxy or asks you to fetch something through a proxy." }, { "title": "Security: Input validation (mandatory)", "body": "Before constructing any shell command, validate every user-provided value. Never interpolate raw user input into shell commands.\n\nInputValidation rulegeoMust be exactly 2 uppercase ASCII letters (ISO 3166-1 alpha-2). Reject anything else.minutesMust be a positive integer between 1 and 1440. Reject non-numeric or out-of-range values.connection_typeMust be one of: any, datacenter, residential. Reject anything else.formatMust be one of: text, json. Reject anything else.URLs (for Step 5)Must start with http:// or https://, contain no shell metacharacters (` $ ( ) ; & `\n\nRules:\n\nNever interpolate raw user input directly into shell commands. Always validate first.\nNever construct -d JSON payloads via string concatenation with user input. Use a safe static template and only insert validated values.\nWhen using curl, always quote the URL and proxy URI arguments.\nPrefer using the agent's built-in HTTP tools (e.g. WebFetch) for fetching user-specified URLs rather than constructing curl commands." }, { "title": "Step 1: Resolve the API key", "body": "Check whether $TPN_API_KEY is set in the environment (OpenClaw injects this automatically from your config):\n\nTest 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.\nIf 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)" }, { "title": "Step 2: Choose response format", "body": "SituationUse formatWhyJust need a working proxy URItext (default)No parsing neededNeed to show structured host/port/user/pass breakdownjsonGives individual fieldsNot suretextSimpler, fewer things to break\n\nIf you choose json, parse the response with jq:\n\ncurl -s ... | jq -r '.vpnConfig.username'\n\nIf jq is not available, use format=text instead — it returns a plain socks5:// URI that needs no parsing.\n\nDo 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." }, { "title": "Step 3: Generate the proxy", "body": "curl -s -X POST https://api.taoprivatenetwork.com/api/v1/proxy/generate \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: $TPN_API_KEY\" \\\n -d '{\"minutes\": 60, \"format\": \"text\", \"connection_type\": \"any\"}'\n\nMap the user's request to these parameters:\n\nFieldTypeRequiredDefaultDescriptionminutesintegeryes—Lease duration (1–1440). Default to 60 if not specified.geostringnoanyISO country code (e.g. \"US\", \"DE\", \"JP\")formatstringnotext\"text\" for URI string, \"json\" for objectconnection_typestringnoany\"any\", \"datacenter\", or \"residential\"\n\nSafe 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." }, { "title": "Step 4: Present the result", "body": "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:\n\nStructured config block (host, port, username, password, scheme, expiry)\nFull socks5h:// URI\nA ready-to-paste curl example when relevant" }, { "title": "Step 5: If the user asked you to fetch a URL", "body": "After generating the proxy, make the request yourself. Use socks5:// (not socks5h://) so DNS resolves locally — the validated IP is the connected IP.\n\nUse 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.\n\nURL validation — every check must pass before fetching:\n\nScheme must be http:// or https://\nNo shell metacharacters: ` $ ( ) ; & | < > newlines\nDomain names only — reject raw IP addresses (IPv4 or IPv6)\nReject internal hostnames: *.internal, *.local, *.localhost, *.localdomain, *.corp, *.lan, metadata.*, single-label hostnames\nHostname must resolve via local DNS — reject unresolvable hostnames\nResolved 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\n\nFallback — curl (only if WebFetch is unavailable). Always double-quote the URL and proxy URI:\n\ncurl --proxy \"socks5://username:password@ip:port\" \\\n --connect-timeout 10 --max-time 30 \\\n \"https://validated-target-url.com\"\n\nReturn the response content to the user — the goal is a complete answer, not a proxy they still need to use themselves." }, { "title": "Examples", "body": "These show exactly what users ask and what you should respond. Study these — they are the gold standard.\n\nUser: \"Give me a socks5 config for Belgium\"\n\nYou: (generate a BE proxy yourself, then respond:)\n\nHere's your Belgian SOCKS5 proxy (valid 60 minutes):\nHost: 185.42.170.3\nPort: 1080\nUsername: u_0CKaBqdE\nPassword: p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V\nScheme: socks5h\nExpires: 2026-02-16T15:30:00Z\n\nFull URI: socks5h://u_0CKaBqdE:p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V@185.42.170.3:1080\ncurl example:\ncurl --proxy socks5h://u_0CKaBqdE:p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V@185.42.170.3:1080 \\\n --connect-timeout 10 --max-time 30 \\\n https://ipv4.icanhazip.com\n\nThis should return a Belgian IP. The proxy expires in 60 minutes — let me know if you need a longer lease.\n\nUser: \"Show me a curl command that proxies over Germany\"\n\nYou: (generate a DE proxy yourself, then respond:)\n\nHere's a curl command routed through a German proxy:\ncurl --proxy socks5h://u_0E4k7kJ6:p_z2HsXTEXJHYiobwCcfOaU1YMS1tg3m0i@5.39.255.64:1080 \\\n --connect-timeout 10 --max-time 30 \\\n https://example.com\n\nReplace https://example.com with your target URL. This proxy expires at 2026-02-16T14:47:20Z.\n\nUser: \"Call icanhazip.com from the Netherlands\"\n\nYou: (generate an NL proxy yourself, fetch icanhazip.com through it, then respond:)\n\nI fetched https://ipv4.icanhazip.com through a Dutch proxy. The response:\n82.148.30.91\n\nThat's the exit IP in the Netherlands. The proxy is still active until 2026-02-16T15:12:00Z if you need more requests.\n\nUser: \"I need a residential US proxy for 2 hours\"\n\nYou: (generate a US residential proxy with minutes=120, then respond:)\n\nHere's your US residential proxy (valid 2 hours, 25 credits):\nHost: 68.210.185.149\nPort: 1080\nUsername: u_02NyffuT\nPassword: p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn\nScheme: socks5h\nType: residential\nExpires: 2026-02-16T16:41:00Z\n\nFull URI: socks5h://u_02NyffuT:p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn@68.210.185.149:1080\nResidential IPs are less likely to be blocked. Let me know if you need a different country.\n\nUser: \"How many credits do I have left?\"\n\nYou: (call GET /api/v1/user/balance yourself, then respond:)\n\nYou have 74 credits remaining.\nFor reference, a 60-minute proxy costs 20 credits and a 10-minute proxy costs 10 credits. You can buy more at https://api.taoprivatenetwork.com — packages start at 1,000 credits for $9.99.\n\nUser: \"Use a proxy to check if my site looks right from Germany\"\n\nYou: (generate a DE proxy, fetch their site through it, then respond:)\n\nI fetched your site through a German proxy (IP: 91.203.50.12):\n\nStatus: 200 OK\nContent-Language: de — looks like your site detected the German IP and served the German version\nPage title: \"Willkommen bei Example\"\n\nEverything seems to be working correctly for German visitors. Want me to check from another country?\n\nUser: \"Set up TPN\" / \"How do I get started with TPN?\"\n\nYou: (check if a key already exists — if yes, tell them they're set up; if no:)\n\nTo get started with TPN:\n\nGo to https://api.taoprivatenetwork.com and create an account\nFrom the dashboard, create an API key (it'll look like tpn-abc123...)\nYour first key comes with 100 free credits — enough for about 5 one-hour proxies\n\nOnce you have the key, share it with me and I'll save it for future sessions. Then I can generate proxies for you anytime.\n\nThe pattern: the user asks, you act, you return results. You never tell the user how to call the API — you call it yourself and hand them the output." }, { "title": "API Reference", "body": "Base URL: https://api.taoprivatenetwork.com\n\nAuthentication: Pass X-API-Key: as a request header. Not Authorization: Bearer." }, { "title": "Endpoints", "body": "MethodPathAuthDescriptionPOST/api/v1/proxy/generateAPI keyGenerate SOCKS5 proxyPOST/api/v1/vpn/generateAPI keyGenerate WireGuard VPNGET/api/v1/user/balanceAPI keyCheck credit balanceGET/api/v1/vpn/countriesnoneList available countriesPOST/api/v1/vpn/costnoneCalculate credit costGET/api/v1/vpn/statsnoneNetwork statisticsGET/api/v1/healthnoneHealth checkPOST/api/v1/x402/proxy/generatex402Generate SOCKS5 proxy (x402)POST/api/v1/x402/vpn/generatex402Generate WireGuard VPN (x402)" }, { "title": "Response shapes", "body": "/proxy/generate with format=text:\n\n{\n \"success\": true,\n \"vpnConfig\": \"socks5://u_02NyffuT:p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn@9.160.73.2:1080\",\n \"minutes\": 60,\n \"expiresAt\": \"2026-02-14T19:08:25.690Z\",\n \"creditsUsed\": 20,\n \"type\": \"socks5\"\n}\n\n/proxy/generate with format=json:\n\n{\n \"success\": true,\n \"vpnConfig\": {\n \"username\": \"u_0CKaBqdE\",\n \"password\": \"p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V\",\n \"ip_address\": \"68.210.185.149\",\n \"port\": 1080\n },\n \"minutes\": 60,\n \"expiresAt\": \"2026-02-14T19:08:23.958Z\",\n \"creditsUsed\": 20,\n \"usedFallback\": false,\n \"type\": \"socks5\",\n \"connection_type\": \"any\"\n}" }, { "title": "/vpn/countries query parameters", "body": "ParamTypeDefaultDescriptionformatstringjson\"json\" for array, \"text\" for newline-separatedtypestringcode\"code\" for ISO codes, \"name\" for full namesconnection_typestringany\"any\", \"datacenter\", or \"residential\"" }, { "title": "Using the proxy (for user-facing code examples)", "body": "Only show these if the user explicitly asks \"how do I use this in my code?\" — otherwise just hand them the config.\n\nUser-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.)\n\nIf proxy credentials contain special characters (@, :, /, #, ?), percent-encode them (e.g. p@ss → p%40ss).\n\ncurl:\n\ncurl --proxy socks5h://username:password@ip_address:port \\\n --connect-timeout 10 --max-time 30 \\\n https://ipv4.icanhazip.com\n\nNode.js:\n\nimport { SocksProxyAgent } from 'socks-proxy-agent'\nimport fetch from 'node-fetch'\n\nconst agent = new SocksProxyAgent( 'socks5h://username:password@ip_address:1080' )\nconst controller = new AbortController()\nconst timeout = setTimeout( () => controller.abort(), 30_000 )\n\nconst response = await fetch( 'https://ipv4.icanhazip.com', { agent, signal: controller.signal } )\nclearTimeout( timeout )\nconsole.log( await response.text() )\n\nPython:\n\nimport requests\n\nproxies = {\n 'http': 'socks5h://username:password@ip_address:1080',\n 'https': 'socks5h://username:password@ip_address:1080'\n}\n\nresponse = requests.get( 'https://ipv4.icanhazip.com', proxies=proxies, timeout=( 10, 30 ) )\nprint( response.text )\n\nSee {baseDir}/references/api-examples.md for end-to-end examples (generate + use) in curl, JS, Node.js, and Python." }, { "title": "Credit Costs", "body": "Formula: credits = ceil( 4.1 × minutes ^ 0.375 )\n\nDurationCredits1 min55 min810 min1030 min1560 min20120 min25720 min491440 min63\n\nUse POST /api/v1/vpn/cost with {\"minutes\": N} to calculate before purchasing.\n\nCredit packages: Starter 1,000/$9.99 · Pro 5,000/$49.99 · Premium 20,000/$199.99" }, { "title": "Troubleshooting & Operational Notes", "body": "ProblemSolution401 UnauthorizedVerify API key is valid — use X-API-Key header, not Bearer402 Payment RequiredInsufficient credits — buy more or use the x402 flow503 Service UnavailableNo miners available — credits are refunded, retry laterConnection timeoutProxy lease may have expired — generate a new oneDNS not resolving (user)Use socks5h:// (with h) for remote DNS resolutionDNS not resolving (agent)Agent uses socks5:// — verify local DNS resolution in check 5\n\nOperational rules:\n\nUser-facing credentials and code examples: always use socks5h:// for DNS privacy\nAgent-side fetching (Step 5): always use socks5:// so local DNS validation is authoritative\nCheck credit balance with GET /api/v1/user/balance before generating proxies in bulk\nProxy leases expire at expiresAt — never cache or reuse credentials beyond that time\nIf a 503 occurs, credits are refunded automatically — retry after a short delay" }, { "title": "x402 Payment Flow (Advanced)", "body": "The x402 protocol enables pay-per-request access using USDC on Base. No account or API key needed — ideal for autonomous agents that already support x402.\n\nIf you are an x402-capable agent, you already know how to handle the payment handshake. The TPN x402 endpoints follow the standard protocol:\n\nPOST /api/v1/x402/proxy/generate — returns HTTP 402 with a standard payment-required header\nComplete the x402 payment flow per the protocol specification\nRetry with the payment header to receive SOCKS5 credentials\n\nSame request body as the centralised endpoint. No X-API-Key needed.\n\nSee {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." }, { "title": "Links", "body": "Dashboard & Account: https://api.taoprivatenetwork.com\nAPI Docs: https://api.taoprivatenetwork.com/docs/getting-started/\nSwagger UI: https://api.taoprivatenetwork.com/api-docs/\nOpenAPI Spec: https://api.taoprivatenetwork.com/api-docs/openapi.json\nLLM-friendly docs: https://api.taoprivatenetwork.com/docs/llms-full.txt\nx402 Protocol: https://www.x402.org" } ], "body": "TPN Decentralized SOCKS5 Proxy\n\nRoute web traffic through Tao Private Network's decentralized SOCKS5 proxies — a Bittensor subnet (SN65) with commercial and residential exit nodes across 80+ countries.\n\nAsk this skill things like:\n\nOpen https://ipv4.icanhazip.com through a proxy in Germany\nShow me a curl command that proxies google.com through a US ip address\nI need a socks5 proxy in Japan for 30 minutes\nWhich countries are available on TPN for proxies?\nSecurity Posture\nAspect\tDetail\nEnvironment variables\tTPN_API_KEY — existence-checked only ([ -n \"$TPN_API_KEY\" ]), never echoed or logged\nFiles read/written\tNone\nOther secrets accessed\tNone — no signing keys, no credentials beyond TPN_API_KEY\nNetwork destinations\tapi.taoprivatenetwork.com (API calls) + user-specified URLs (validated per Step 5)\nx402 signing\tHandled entirely by external libraries (@x402/*); this skill provides endpoint URLs only\nThis is an action skill\n\nThis skill executes API calls and returns results directly — it does not output documentation or instructions for the user to follow.\n\nExpected behaviour:\n\nCall the TPN API yourself (via curl or equivalent) and return the full proxy credentials to the user.\nWhen the user asks you to fetch a URL through a proxy, make that request yourself too.\nShow the full SOCKS5 credentials (username, password, host, port) — these are short-lived and scoped to the proxy lease.\nThe 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.\nIf no API key exists, guide the user through account setup — that's the one step only they can do.\n\nA good check: if your response contains \"you can run this command to…\" or \"use this curl to generate…\", reconsider — the user invoked this skill expecting you to run the command and hand them the output.\n\nStep-by-Step Procedure\n\nFollow this procedure every time the user requests a proxy or asks you to fetch something through a proxy.\n\nSecurity: Input validation (mandatory)\n\nBefore constructing any shell command, validate every user-provided value. Never interpolate raw user input into shell commands.\n\nInput\tValidation rule\ngeo\tMust be exactly 2 uppercase ASCII letters (ISO 3166-1 alpha-2). Reject anything else.\nminutes\tMust be a positive integer between 1 and 1440. Reject non-numeric or out-of-range values.\nconnection_type\tMust be one of: any, datacenter, residential. Reject anything else.\nformat\tMust be one of: text, json. Reject anything else.\nURLs (for Step 5)\tMust start with http:// or https://, contain no shell metacharacters (` $ ( ) ; & `\n\nRules:\n\nNever interpolate raw user input directly into shell commands. Always validate first.\nNever construct -d JSON payloads via string concatenation with user input. Use a safe static template and only insert validated values.\nWhen using curl, always quote the URL and proxy URI arguments.\nPrefer using the agent's built-in HTTP tools (e.g. WebFetch) for fetching user-specified URLs rather than constructing curl commands.\nStep 1: Resolve the API key\n\nCheck whether $TPN_API_KEY is set in the environment (OpenClaw injects this automatically from your config):\n\nTest 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.\nIf 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)\nStep 2: Choose response format\nSituation\tUse format\tWhy\nJust need a working proxy URI\ttext (default)\tNo parsing needed\nNeed to show structured host/port/user/pass breakdown\tjson\tGives individual fields\nNot sure\ttext\tSimpler, fewer things to break\n\nIf you choose json, parse the response with jq:\n\ncurl -s ... | jq -r '.vpnConfig.username'\n\n\nIf jq is not available, use format=text instead — it returns a plain socks5:// URI that needs no parsing.\n\nDo 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.\n\nStep 3: Generate the proxy\ncurl -s -X POST https://api.taoprivatenetwork.com/api/v1/proxy/generate \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: $TPN_API_KEY\" \\\n -d '{\"minutes\": 60, \"format\": \"text\", \"connection_type\": \"any\"}'\n\n\nMap the user's request to these parameters:\n\nField\tType\tRequired\tDefault\tDescription\nminutes\tinteger\tyes\t—\tLease duration (1–1440). Default to 60 if not specified.\ngeo\tstring\tno\tany\tISO country code (e.g. \"US\", \"DE\", \"JP\")\nformat\tstring\tno\ttext\t\"text\" for URI string, \"json\" for object\nconnection_type\tstring\tno\tany\t\"any\", \"datacenter\", or \"residential\"\n\nSafe 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.\n\nStep 4: Present the result\n\nShow 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:\n\nStructured config block (host, port, username, password, scheme, expiry)\nFull socks5h:// URI\nA ready-to-paste curl example when relevant\nStep 5: If the user asked you to fetch a URL\n\nAfter generating the proxy, make the request yourself. Use socks5:// (not socks5h://) so DNS resolves locally — the validated IP is the connected IP.\n\nUse 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.\n\nURL validation — every check must pass before fetching:\n\nScheme must be http:// or https://\nNo shell metacharacters: ` $ ( ) ; & | < > newlines\nDomain names only — reject raw IP addresses (IPv4 or IPv6)\nReject internal hostnames: *.internal, *.local, *.localhost, *.localdomain, *.corp, *.lan, metadata.*, single-label hostnames\nHostname must resolve via local DNS — reject unresolvable hostnames\nResolved 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\n\nFallback — curl (only if WebFetch is unavailable). Always double-quote the URL and proxy URI:\n\ncurl --proxy \"socks5://username:password@ip:port\" \\\n --connect-timeout 10 --max-time 30 \\\n \"https://validated-target-url.com\"\n\n\nReturn the response content to the user — the goal is a complete answer, not a proxy they still need to use themselves.\n\nExamples\n\nThese show exactly what users ask and what you should respond. Study these — they are the gold standard.\n\nUser: \"Give me a socks5 config for Belgium\"\n\nYou: (generate a BE proxy yourself, then respond:)\n\nHere's your Belgian SOCKS5 proxy (valid 60 minutes):\n\nHost: 185.42.170.3\nPort: 1080\nUsername: u_0CKaBqdE\nPassword: p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V\nScheme: socks5h\nExpires: 2026-02-16T15:30:00Z\n\n\nFull URI: socks5h://u_0CKaBqdE:p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V@185.42.170.3:1080\n\ncurl example:\n\ncurl --proxy socks5h://u_0CKaBqdE:p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V@185.42.170.3:1080 \\\n --connect-timeout 10 --max-time 30 \\\n https://ipv4.icanhazip.com\n\n\nThis should return a Belgian IP. The proxy expires in 60 minutes — let me know if you need a longer lease.\n\nUser: \"Show me a curl command that proxies over Germany\"\n\nYou: (generate a DE proxy yourself, then respond:)\n\nHere's a curl command routed through a German proxy:\n\ncurl --proxy socks5h://u_0E4k7kJ6:p_z2HsXTEXJHYiobwCcfOaU1YMS1tg3m0i@5.39.255.64:1080 \\\n --connect-timeout 10 --max-time 30 \\\n https://example.com\n\n\nReplace https://example.com with your target URL. This proxy expires at 2026-02-16T14:47:20Z.\n\nUser: \"Call icanhazip.com from the Netherlands\"\n\nYou: (generate an NL proxy yourself, fetch icanhazip.com through it, then respond:)\n\nI fetched https://ipv4.icanhazip.com through a Dutch proxy. The response:\n\n82.148.30.91\n\n\nThat's the exit IP in the Netherlands. The proxy is still active until 2026-02-16T15:12:00Z if you need more requests.\n\nUser: \"I need a residential US proxy for 2 hours\"\n\nYou: (generate a US residential proxy with minutes=120, then respond:)\n\nHere's your US residential proxy (valid 2 hours, 25 credits):\n\nHost: 68.210.185.149\nPort: 1080\nUsername: u_02NyffuT\nPassword: p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn\nScheme: socks5h\nType: residential\nExpires: 2026-02-16T16:41:00Z\n\n\nFull URI: socks5h://u_02NyffuT:p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn@68.210.185.149:1080\n\nResidential IPs are less likely to be blocked. Let me know if you need a different country.\n\nUser: \"How many credits do I have left?\"\n\nYou: (call GET /api/v1/user/balance yourself, then respond:)\n\nYou have 74 credits remaining.\n\nFor reference, a 60-minute proxy costs 20 credits and a 10-minute proxy costs 10 credits. You can buy more at https://api.taoprivatenetwork.com — packages start at 1,000 credits for $9.99.\n\nUser: \"Use a proxy to check if my site looks right from Germany\"\n\nYou: (generate a DE proxy, fetch their site through it, then respond:)\n\nI fetched your site through a German proxy (IP: 91.203.50.12):\n\nStatus: 200 OK\nContent-Language: de — looks like your site detected the German IP and served the German version\nPage title: \"Willkommen bei Example\"\n\nEverything seems to be working correctly for German visitors. Want me to check from another country?\n\nUser: \"Set up TPN\" / \"How do I get started with TPN?\"\n\nYou: (check if a key already exists — if yes, tell them they're set up; if no:)\n\nTo get started with TPN:\n\nGo to https://api.taoprivatenetwork.com and create an account\nFrom the dashboard, create an API key (it'll look like tpn-abc123...)\nYour first key comes with 100 free credits — enough for about 5 one-hour proxies\n\nOnce you have the key, share it with me and I'll save it for future sessions. Then I can generate proxies for you anytime.\n\nThe pattern: the user asks, you act, you return results. You never tell the user how to call the API — you call it yourself and hand them the output.\n\nAPI Reference\n\nBase URL: https://api.taoprivatenetwork.com\n\nAuthentication: Pass X-API-Key: as a request header. Not Authorization: Bearer.\n\nEndpoints\nMethod\tPath\tAuth\tDescription\nPOST\t/api/v1/proxy/generate\tAPI key\tGenerate SOCKS5 proxy\nPOST\t/api/v1/vpn/generate\tAPI key\tGenerate WireGuard VPN\nGET\t/api/v1/user/balance\tAPI key\tCheck credit balance\nGET\t/api/v1/vpn/countries\tnone\tList available countries\nPOST\t/api/v1/vpn/cost\tnone\tCalculate credit cost\nGET\t/api/v1/vpn/stats\tnone\tNetwork statistics\nGET\t/api/v1/health\tnone\tHealth check\nPOST\t/api/v1/x402/proxy/generate\tx402\tGenerate SOCKS5 proxy (x402)\nPOST\t/api/v1/x402/vpn/generate\tx402\tGenerate WireGuard VPN (x402)\nResponse shapes\n\n/proxy/generate with format=text:\n\n{\n \"success\": true,\n \"vpnConfig\": \"socks5://u_02NyffuT:p_CIYLqgIyLZ1rSvZGQbdh3lyxQQBcBsQn@9.160.73.2:1080\",\n \"minutes\": 60,\n \"expiresAt\": \"2026-02-14T19:08:25.690Z\",\n \"creditsUsed\": 20,\n \"type\": \"socks5\"\n}\n\n\n/proxy/generate with format=json:\n\n{\n \"success\": true,\n \"vpnConfig\": {\n \"username\": \"u_0CKaBqdE\",\n \"password\": \"p_sT6yM3zabqRuhqrahzGOl4i4RTEDgQ7V\",\n \"ip_address\": \"68.210.185.149\",\n \"port\": 1080\n },\n \"minutes\": 60,\n \"expiresAt\": \"2026-02-14T19:08:23.958Z\",\n \"creditsUsed\": 20,\n \"usedFallback\": false,\n \"type\": \"socks5\",\n \"connection_type\": \"any\"\n}\n\n/vpn/countries query parameters\nParam\tType\tDefault\tDescription\nformat\tstring\tjson\t\"json\" for array, \"text\" for newline-separated\ntype\tstring\tcode\t\"code\" for ISO codes, \"name\" for full names\nconnection_type\tstring\tany\t\"any\", \"datacenter\", or \"residential\"\nUsing the proxy (for user-facing code examples)\n\nOnly show these if the user explicitly asks \"how do I use this in my code?\" — otherwise just hand them the config.\n\nUser-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.)\n\nIf proxy credentials contain special characters (@, :, /, #, ?), percent-encode them (e.g. p@ss → p%40ss).\n\ncurl:\n\ncurl --proxy socks5h://username:password@ip_address:port \\\n --connect-timeout 10 --max-time 30 \\\n https://ipv4.icanhazip.com\n\n\nNode.js:\n\nimport { SocksProxyAgent } from 'socks-proxy-agent'\nimport fetch from 'node-fetch'\n\nconst agent = new SocksProxyAgent( 'socks5h://username:password@ip_address:1080' )\nconst controller = new AbortController()\nconst timeout = setTimeout( () => controller.abort(), 30_000 )\n\nconst response = await fetch( 'https://ipv4.icanhazip.com', { agent, signal: controller.signal } )\nclearTimeout( timeout )\nconsole.log( await response.text() )\n\n\nPython:\n\nimport requests\n\nproxies = {\n 'http': 'socks5h://username:password@ip_address:1080',\n 'https': 'socks5h://username:password@ip_address:1080'\n}\n\nresponse = requests.get( 'https://ipv4.icanhazip.com', proxies=proxies, timeout=( 10, 30 ) )\nprint( response.text )\n\n\nSee {baseDir}/references/api-examples.md for end-to-end examples (generate + use) in curl, JS, Node.js, and Python.\n\nCredit Costs\n\nFormula: credits = ceil( 4.1 × minutes ^ 0.375 )\n\nDuration\tCredits\n1 min\t5\n5 min\t8\n10 min\t10\n30 min\t15\n60 min\t20\n120 min\t25\n720 min\t49\n1440 min\t63\n\nUse POST /api/v1/vpn/cost with {\"minutes\": N} to calculate before purchasing.\n\nCredit packages: Starter 1,000/$9.99 · Pro 5,000/$49.99 · Premium 20,000/$199.99\n\nTroubleshooting & Operational Notes\nProblem\tSolution\n401 Unauthorized\tVerify API key is valid — use X-API-Key header, not Bearer\n402 Payment Required\tInsufficient credits — buy more or use the x402 flow\n503 Service Unavailable\tNo miners available — credits are refunded, retry later\nConnection timeout\tProxy lease may have expired — generate a new one\nDNS not resolving (user)\tUse socks5h:// (with h) for remote DNS resolution\nDNS not resolving (agent)\tAgent uses socks5:// — verify local DNS resolution in check 5\n\nOperational rules:\n\nUser-facing credentials and code examples: always use socks5h:// for DNS privacy\nAgent-side fetching (Step 5): always use socks5:// so local DNS validation is authoritative\nCheck credit balance with GET /api/v1/user/balance before generating proxies in bulk\nProxy leases expire at expiresAt — never cache or reuse credentials beyond that time\nIf a 503 occurs, credits are refunded automatically — retry after a short delay\nx402 Payment Flow (Advanced)\n\nThe x402 protocol enables pay-per-request access using USDC on Base. No account or API key needed — ideal for autonomous agents that already support x402.\n\nIf you are an x402-capable agent, you already know how to handle the payment handshake. The TPN x402 endpoints follow the standard protocol:\n\nPOST /api/v1/x402/proxy/generate — returns HTTP 402 with a standard payment-required header\nComplete the x402 payment flow per the protocol specification\nRetry with the payment header to receive SOCKS5 credentials\n\nSame request body as the centralised endpoint. No X-API-Key needed.\n\nSee {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.\n\nLinks\nDashboard & Account: https://api.taoprivatenetwork.com\nAPI Docs: https://api.taoprivatenetwork.com/docs/getting-started/\nSwagger UI: https://api.taoprivatenetwork.com/api-docs/\nOpenAPI Spec: https://api.taoprivatenetwork.com/api-docs/openapi.json\nLLM-friendly docs: https://api.taoprivatenetwork.com/docs/llms-full.txt\nx402 Protocol: https://www.x402.org" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/actuallymentor/tpn-proxy", "publisherUrl": "https://clawhub.ai/actuallymentor/tpn-proxy", "owner": "actuallymentor", "version": "1.1.2", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/tpn-proxy", "downloadUrl": "https://openagent3.xyz/downloads/tpn-proxy", "agentUrl": "https://openagent3.xyz/skills/tpn-proxy/agent", "manifestUrl": "https://openagent3.xyz/skills/tpn-proxy/agent.json", "briefUrl": "https://openagent3.xyz/skills/tpn-proxy/agent.md" } }