# API overview Source: https://docs.pingnetwork.io/Clients/API-overview ### Getting Started To begin using our API: 1. Obtain your API token by contacting our [support ](https://docs.pingnetwork.io/help/support)team: [support@pingnetwork.io](mailto:support@pingnetwork.io) 2. Choose the appropriate API version for your integration 3. Make requests following the format described in this documentation 4. Handle responses and errors accordingly 5. For detailed endpoint documentation and examples, please refer to the specific API sections that follow. ### Authentication All API requests require authentication using an Authorization token. ``` Authorization: Bearer YOUR\_TOKEN\_HERE ``` To obtain your API token, please contact our support team. Keep your token secure and do not share it with unauthorized parties. ### API Versioning We use route-based versioning to ensure a stable development experience. Each endpoint includes a version prefix in the URL path. Examples: * `v1/customers` - Version 1 of the customers endpoint * `/v2/customers` - Version 2 of the customers endpoint Backward Compatibility Promise: We maintain backward compatibility within each version. This means your integration with a specific API version will continue to work even as we add new features or release newer versions. ### Request and Response Format Our API follows REST principles and uses JSON for both requests and responses. #### Request Format * Content-Type: `application/json` * HTTP methods correspond to operations: * `GET`: Retrieve resources * `POST`: Create resources * `PUT`: Update resources * `DELETE`: Remove resources Example request: ```json POST /v1/customers HTTP/1.1 Host: api.example.com Authorization: Bearer YOUR_TOKEN_HERE Content-Type: application/json { "name": "John Doe", "email": "john.doe@example.com" } ``` #### Response Format All responses are returned in JSON format. Example successful response: ```json { "id": "cust_123456", "name": "John Doe", "email": "john.doe@example.com", "created_at": "2025-02-28T10:30:00Z" } ``` ### Error Handling When an error occurs, the API returns an appropriate HTTP status code along with a JSON response containing error details. #### Common Error Status Codes * `400 Bad Request`: Invalid input or malformed request * `401 Unauthorized`: Authentication failure or invalid token * `429 Too Many Requests`: Rate limit exceeded * `404 Not Found`: Resource not found * `500 Internal Server Error`: Unexpected server error #### Error Response Format ```json { "error": { "code": "invalid_input", "message": "The email address format is invalid", "details": { "field": "email", "value": "invalid-email" } } } ``` ### Rate Limiting To ensure service stability, our API implements rate limiting. When you exceed the allowed number of requests, you'll receive a `429 Too Many Requests status code`. The response headers include information about your current rate limit status: `X-RateLimit-Limit`: Maximum requests allowed in a time window `X-RateLimit-Remaining`: Remaining requests in the current window `X-RateLimit-Reset`: Time (in seconds) until the rate limit resets ### OpenAPI/Swagger Support We provide OpenAPI (formerly known as Swagger) specifications for our API. This offers several advantages: * **Interactive Documentation**: Explore and test our API endpoints directly through a browser interface * **Code Generation**: Generate client libraries in your preferred programming language * **Request/Response Models**: Understand the exact structure of requests and responses Contact us to receive the OpenAPI specification file tailored to your needs. With this file, you can generate custom client libraries that handle the request-response cycle automatically, significantly reducing the development time needed for API integration. # Delete limits that apply to each client individually Source: https://docs.pingnetwork.io/api-reference/client-limits/delete-limits-that-apply-to-each-client-individually swagger.json delete /customer/limits/client # Retrieve limits that apply to each client individually Source: https://docs.pingnetwork.io/api-reference/client-limits/retrieve-limits-that-apply-to-each-client-individually swagger.json get /customer/limits/client # Update limits that apply to each client individually Source: https://docs.pingnetwork.io/api-reference/client-limits/update-limits-that-apply-to-each-client-individually swagger.json patch /customer/limits/client # Delete global limits Source: https://docs.pingnetwork.io/api-reference/global-limits/delete-global-limits swagger.json delete /customer/limits/global # Retrieve global limits for all customer's clients Source: https://docs.pingnetwork.io/api-reference/global-limits/retrieve-global-limits-for-all-customers-clients swagger.json get /customer/limits/global # Update existing global limits Source: https://docs.pingnetwork.io/api-reference/global-limits/update-existing-global-limits swagger.json patch /customer/limits/global # Delete default session limits Source: https://docs.pingnetwork.io/api-reference/session-limits/delete-default-session-limits swagger.json delete /customer/limits/session # Retrieve default session limits Source: https://docs.pingnetwork.io/api-reference/session-limits/retrieve-default-session-limits swagger.json get /customer/limits/session # Update default session limits Source: https://docs.pingnetwork.io/api-reference/session-limits/update-default-session-limits swagger.json patch /customer/limits/session # Create a new session Source: https://docs.pingnetwork.io/api-reference/sessions/create-a-new-session swagger.json post /sessions Creates a new session in the specified zone with the requested connection type # Get session status Source: https://docs.pingnetwork.io/api-reference/sessions/get-session-status swagger.json get /sessions/{id}/status Retrieves the current status of a specific session by ID # Pause a reusable session Source: https://docs.pingnetwork.io/api-reference/sessions/pause-a-reusable-session swagger.json patch /sessions/{id}/pause Pauses an active reusable session, disconnecting all active connections # Resume a paused session Source: https://docs.pingnetwork.io/api-reference/sessions/resume-a-paused-session swagger.json patch /sessions/{id}/resume Resumes a paused reusable session, allowing new connections # Stream session events Source: https://docs.pingnetwork.io/api-reference/sessions/stream-session-events swagger.json get /sessions/events Provides a Server-Sent Events stream of session activity events # List available network zones Source: https://docs.pingnetwork.io/api-reference/zones/list-available-network-zones swagger.json get /zones Returns a list of all available network zones # FAQ Source: https://docs.pingnetwork.io/help/faq Ping is a decentralized bandwidth infrastructure that will revolutionize how internet resources are shared and utilized. Our network will enable users to monetize their unused Internet connection while providing businesses with scalable, cost-effective networking solutions. In Season One you earn 1 Ping Point every 10 minutes while connected to Ping VPN — tracked automatically. Yes! Each account tracks points separately, even on the same network. Yes, Ping supports both desktop and mobile devices, allowing you to participate from multiple devices on the same network. No, multiple accounts per user will not be permitted. This policy helps maintain network integrity and fair reward distribution. Ping Points track your contribution to Ping Network. They reflect how actively you're supporting the protocol — whether by using the app, inviting friends, or joining events. Points are the foundation for seasonal rewards and your future participation in the network. * Advanced encryption and privacy protocols will secure all network activities * Multi-layered security architecture will protect user data * Users will have complete control over their bandwidth sharing preferences Your shared bandwidth will support: * **VPN Data Routing** * **AI Model Development** * **Decentralized Content Delivery** * **Any bandwidth-heavy usecase** Join our [Discord community](https://discord.gg/pingnetwork) for assistance and updates Yes! Your privacy is our highest priority. * Our system is designed with distributed knowledge approach - neither we or node operators have no possibility to track your browsing activity or collect personal data * Only your unused bandwidth will be utilized, completely separate from your personal internet activity * We implement industry-leading security standards and regular system audits to ensure data protection We’re a global team — with members in Argentina, Europe, and South Asia. No. We don't keep any logs. Sadly, we can't recover your account. There’s no fixed timeline, but we’ve publicly announced the seasonal rollout. Read more about seasons [here](https://x.com/PingNetwork_io/status/1922690198548181271). # Support Source: https://docs.pingnetwork.io/help/support If you run into any issues, we’re here to help: • Create a ticket in our [**Discord**](https://discord.gg/pingnetwork)\ • Message us via [**Telegram Support Bot**](https://t.me/pingnetworksupport_bot)\ • Check the [**FAQ**](https://docs.pingnetwork.io/help/faq) for common questions and answers If you need help with onboarding to Ping as developer/business, please, contact us by e-mail:\ [support@pingnetwork.io](mailto:support@pingnetwork.io) # Architecture Source: https://docs.pingnetwork.io/overview/architecture Ping utilizes a decentralized network of nodes to create a universal next-gen networking infrastructure tailored for business needs. By tapping into global resources, including user hardware and dedicated hardware, Ping enables scalable and cost-efficient solutions. Our infrastructure relies on a robust verification layer to ensure secure traffic processing and maintain the integrity of the network. Operating as a rollup on Solana, Ping ensures that essential data is immutably committed to the blockchain, guaranteeing secure and transparent network operations. ## Ping RPC Ping RPC is the gateway that connects clients to the Ping infrastructure, ensuring secure and efficient interaction. It performs two key functions: * **Client Authorization:** Verifies client credentials, billing, and access rights before granting entry to the network * **Server Selection:** Dynamically selects the most suitable servers for user requests based on validator ratings and network load Through Ping RPC, clients benefit from a user-friendly interface for seamless access to the network. At the same time, the infrastructure remains secure as sensitive information is protected, ensuring a robust and reliable system. ## Nodes Ping’s architecture relies on permissionless nodes that efficiently process traffic, ensuring smooth data flow across the network. By eliminating centralized server clusters, this decentralized model allows independent operators to contribute their hardware, enabling global coverage, scalability, and resilience. Ping leverages different types of nodes to cater to various business needs: 1. **Edge Nodes:** These include laptops, smartphones, and routers that act as residential proxies. They are essential for AI-driven web scraping, providing unique IPs that reduce the likelihood of being blocked and significantly improve data collection efficiency. 2. **Server Nodes:** These are dedicated hardware solutions optimized for enterprise-level tasks such as VPN routing and managing high-demand traffic. Server nodes ensure reliability and scalability, making them ideal for businesses with robust infrastructure requirements. When a node is connected, it is automatically registered on the network. Operators are responsible for maintaining uptime, allowing their nodes to relay web requests to public servers effectively. All user data is encrypted, ensuring the highest levels of security and privacy. This encryption means that nodes cannot access complete client information, guaranteeing the confidentiality of user data while maintaining network efficiency. This decentralized node architecture enables Ping to offer secure, scalable, and efficient networking solutions while upholding user privacy and global reliability. ## Validators Validators are a core part of Ping’s protocol. They verify node activity, track performance, and enforce fair reward distribution through smart contracts. Operating on a custom L2, validators process proofs, apply slashing when needed, and help maintain the integrity of the network — all without accessing user data. ## Infrastructure Stack Ping Network is built on top of **Solana**, using it as the foundation for all critical onchain operations — including token logic, reward distribution, and validator registry updates. Solana’s performance and low fees make it ideal for handling protocol-level transactions at scale. \ To secure its validator layer, Ping integrates **Jito’s re-staking model**, allowing validators to lock liquidity while earning additional rewards. This model supports economic security and enables **slashing** mechanisms for validators who misbehave or underperform.\ Governance, validator logic, and oracle coordination are managed through **Cambrian’s Node Consensus Network (NCN)** and **Proof of Authority (PoA)** tooling. NCN Operators deploy validator code, manage metadata oracles, and help drive protocol evolution on a dedicated L2 environment. ## What lives where * **On Solana**: token minting and burning, reward distribution, validator metadata, governance state * **On L2**: proof verification, fraud detection, smart contracts for reputation and payouts * **Offchain**: node activity, bandwidth metrics, and network monitoring handled through Ping’s backend Ping’s infrastructure stack is designed for long-term resilience. It’s decentralized, modular, and built to scale with real-world usage. # How to Contribute Source: https://docs.pingnetwork.io/overview/contribute Each season of Ping introduces new ways to contribute. Season One is live now.\ Your mission: use the app, stay connected, and help us showcase the infrastructure and build the biggest DePIN community. You earn **1 Ping Point every 10 minutes**— plus boosts and referral bonuses. 🡒 [Learn how Ping Points work →](https://docs.pingnetwork.io/overview/points) Spread the word. Whether it’s a meme, a thread, or a deep dive — quality content gets noticed. Share your takes on: X (Twitter), TikTok, Telegram, be sure to tag **@pingnetwork\_io** so we don't miss you. Bring your frens into Ping Network. Each invite helps grow the network — and earns you a **+15%** from their farm. They get a **+10% boost** too. Your referral code is in the app. ## ## What’s Next — Season Two In Season Two, Ping will launch its testnet — and contributors will be able to: run a node, share bandwidth, help us scale the protocol. More info coming soon. # Key Features Source: https://docs.pingnetwork.io/overview/key-features Ping Network is redefining how bandwidth is shared and used, unlocking the potential of decentralized infrastructure for businesses and individuals alike. With its innovative approach, Ping delivers solutions that are efficient, scalable, and tailored to business needs. ## One infra for every use-case Ping Network provides universal bandwidth infrastructure that can support any networking use-case. Whether it’s VPN routing, large-scale data scraping, or global content delivery, Ping fits each business need. It’s built to power the technologies of today and tomorrow. ## Fully autonomous Ping Network is built to be fully autonomous. No setup or delivery delays — businesses just connect through APIs and start enjoying the full power of Ping’s infra. Meanwhile, node operators get rewarded automatically based on onchain proofs. ## Unmatched global coverage With Ping, businesses don’t need 30 providers to achieve global reach. Our network spans over 190 countries — far beyond the average coverage of traditional cloud or bare-metal setups. ## Scale on demand When demand spikes, Ping Network scales in real time. No waiting for hardware delivery. The network expands based on real-time usage, ensuring consistent performance without the need for manual intervention. ## Decentralized resilience With no single point of failure, Ping offers unmatched network resilience. Thousands of independent contributors power the network, ensuring 99.9999% uptime. ## Compatible with any hardware Ping nodes operate across a wide range of hardware — from enterprise servers to consumer devices. This flexibility gives businesses access to diverse, cost-efficient bandwidth resources tailored to their specific needs. ## Cost-efficiency Most Internet infrastructure is underutilized. Servers, routers, and other devices often sit idle, wasting energy and driving up costs. Ping puts that idle hardware to work. By aggregating unused bandwidth from homes, offices, and data centers, we help the market run leaner and more efficiently. Better utilization means fewer wasted resources, lower infrastructure costs, and pricing that reflects actual usage, not overprovisioning. That’s good for the ecosystem and even better for end users. ## Dynamic node incentives Ping Network is built to grow where demand exists. As network usage increases in specific regions, incentives automatically adjust to attract more contributors there. This dynamic model ensures better coverage in underserved areas and builds a truly decentralized, high-performance infrastructure layer. # Nodes Source: https://docs.pingnetwork.io/overview/nodes Nodes are the core of Ping Network. 2ping Docs NODES Pn Nodes handle tasks like routing VPN traffic, scraping web data, monitoring uptime and latency, and accelerating content delivery. All powered by real user devices and enterprise grade hardware around the world. Every node runs a Universal Agent, which connects the device to the network and manages things like registration, session handling, and stats reporting. The Universal Agent is responsible for: * Registering the node with Ping validators * Handling authentication and session authorization * Sending performance data and traffic reports * Receiving module updates and task assignments * Coordinating traffic flow between modules On top of this, nodes can activate specific modules based on their hardware and configuration. This design keeps the system modular and scalable. Each node contributes based on its capacity, and the network adjusts dynamically as new devices join or tasks change. ## **Universal Agent and Modules** The Universal Agent is always active. It handles communication with the network and coordinates everything the node does. Additional modules are activated automatically, depending on the capabilities of the device. These include VPN client/server, proxy, scraping, relay, cache, and monitoring. Ping UNA1 1 Pn ## **Example Configurations** Nodes can run on different types of hardware. Each configuration has a different role in the network. Ping UNA2 1 Pn ### **Mobile Edge Node** Runs on smartphones or laptops. Supports outbound functions like VPN Client, Scraping, and Network Monitoring. Cannot run heavy modules or serve inbound traffic. ### **Server Node** Runs on VPS or dedicated servers. Can support all modules including VPN Server, Proxy Server, Relay, Cache, and Monitoring. Designed for high throughput and inbound tasks. ### **Home Router Node** Runs on consumer routers and gateways. Can provide proxy routing, reverse proxy, monitoring and scraping. Nodes come in many forms, but they all serve the same purpose: move data where it’s needed. Whether it’s a phone, router, or server, each device strengthens the network, improves coverage, and helps deliver faster, cheaper Internet infrastructure. # Ping Points Source: https://docs.pingnetwork.io/overview/points Ping Points help reward contributors and track everyone’s impact in the Ping Network 2 ping-docs-PP (2).png ## How Points are earned Ping Points are currently earned as part of **Season One**. This season focuses on growing the contributor network and showcasing the Ping infrastructure in action. The main way to earn points right now is through active VPN connection in the [**Ping app**](https://download.pingnetwork.io). More ways to earn and participate will be introduced in future seasons. ### Basic rules Every active user earns **1 Point for every 10 minutes** connected through the Ping app. Points are calculated gradually — they update in real time, not in delayed blocks. Good to know: * You can farm Points even if the app is running in the background or your screen is off (as long as the VPN is active) * There’s no need to micromanage — stay connected, and you keep earning * You can be logged in under one account on multiple devices, but you will still earn 1 point per 10 minutes total (without boosts) ### Referral system The referral program helps grow the Ping Network and rewards both sides. * **Invited users** get a **permanent +10% boost** to their Points farming * **Referrers** earn **15% of the total Points** generated by their invitees (after all boosts are applied) Referral rewards are **added on top** — they don’t reduce what the invited user earns.\ Example: If your invitee farms 100 Points in a day (including points from boosts), you receive an extra 15 Points. ## Boosts **Boosts** are extra bonuses that increase how many points you earn. You can get them by doing tasks in the app. ### **How Boosts Work** * All active boosts are **added together (not multiplied)** and applied to your base farm rate. * Example: +0.5 boost +1.0 boost = **+1.5 total boost** If your base rate is 6 points per hour, you’ll earn **9 points per hour**. * Boosts are **time-based** — they continue running even if you're offline. VPN activity only is affected (1 point per 10 minutes). Referral points are **not** boosted. ### Types of Boosts There are two kinds of boosts: * One-time Boosts Gives a short-term multiplier (e.g. +0.1x to +1.0x for a few hours). * Lifetime Boosts The bonus stays active forever. ## Seasons Ping Points operate on a **seasonal system**. At the end of each season, a **snapshot** is taken of all users’ contributions. **Season One** is focused on building contributors network and showcasing Ping Network infrastructure through the VPN. Future seasons will introduce new earning methods and rewards — details will be announced as they roll out. # Solutions and Use-cases Source: https://docs.pingnetwork.io/overview/solutions Ping Network is a universal layer for any bandwidth-heavy application ## **AI Data Crawling** AI systems require consistent access to diverse and real-time web data. Traditional crawling setups face geo-blocks, high latency, and limited proxy availability. Ping Network enables scalable, undetectable data collection by leveraging real IPs from globally distributed contributors. Businesses benefit from access to authentic traffic routes and higher data success rates without the need for complex infrastructure or proxy chains. The protocol ensures flexibility, lower costs, and broader reach — key advantages for AI companies building at scale. ## **Content Delivery (CDN)** Content platforms need reliable global distribution with low latency. Traditional CDNs rely on static infrastructure that is expensive to scale and limited in reach. Ping Network provides a dynamic, distributed alternative. As more nodes join the network, coverage expands at city-level granularity, improving delivery speed and resilience. Businesses benefit from faster load times, reduced infrastructure costs, and improved availability — especially in underserved regions. ## **VPN Infrastructure** VPN services require high uptime, speed, and broad geo-coverage. Centralized infrastructure creates performance bottlenecks and operational overhead. With Ping Network, VPN providers gain instant access to high-performance bandwidth from enterprise-grade nodes — with the added benefit of residential and edge traffic routes across 190+ countries, all powered by a decentralized contributor network. This setup reduces costs, improves reliability, and removes dependency on static servers. It enables VPN apps to scale quickly and maintain performance under high demand. ## **Geodata and SLA Monitoring** Monitoring tools need access to IPs and bandwidth across regions to verify service availability, latency, and performance. Ping Network provides region-specific coverage using edge devices — far beyond typical cloud-based PoPs. This allows for better SLA enforcement and accurate analytics across real-world conditions. ## **General Bandwidth Use Cases** Any bandwidth-heavy application can benefit from Ping Network. The protocol’s modular architecture and hardware-agnostic design enable quick onboarding and efficient scaling across a wide range of verticals. # Validators Source: https://docs.pingnetwork.io/overview/validators Validators are a critical part of Ping’s decentralized infrastructure. ## Introduction Validators operate on a specialized Layer 2 (L2) system built on top of Solana, and are responsible for validating network activity, managing access, and distributing rewards. Validators are a core part of the Ping Network. They help keep the network secure, fair, and operational by handling key responsibilities: * Verify node performance * Maintain a live registry of active providers * Ensure the bandwidth network runs smoothly They play a central role in scaling the Ping Network, without compromising on speed, privacy, or decentralization. > Ping’s architecture is built with strict data boundaries — validators never have access to user traffic or private content. Scheme1 Pn ## Discovery AVS Discovery AVS is part of the Ping backend. It helps nodes find available validators and sends relevant data to the web app. It also monitors the network for abnormal behavior. When a malicious node is detected, AVS signs a penalty transaction and broadcasts it to the L2 ledger — triggering enforcement. > AVS operates strictly at the network level. It does not access or analyze user traffic. > > Its role is to maintain the integrity of the system without compromising privacy. ## NCN — Node Consensus Network The Node Consensus Network (NCN) allows nodes and validators to discover and interact with each other trustlessly. * Validators publish node’s metadata (IP, uptime, performance) to a Solana-based oracle. * Nodes query this oracle to find available validators. * Nodes then submit signed proofs to validators. Validator setup and registry management is supported by the **Cambrian SDK**, which also enables governance operations and validator coordination. Scheme2 Pn ## Proofs & Smart Contracts (L2) Ping’s L2 validator layer is powered by smart contracts that handle validation logic, rewards, and reputation. Validators process two main types of proofs: * **Proof-of-Contribution (PoC):** Submitted by nodes to verify bandwidth usage, uptime, and service quality. * **Proof-of-Fraud (PoF):** Triggered when a node acts maliciously or incorrectly. PoF is signed by AVS and sent to L2. Smart contracts involved: * **Rewards Oracle:** Calculates node rewards based on activity and history. * **Reputation Oracle:** Tracks node performance and adjusts rewards dynamically. > All reward and validation logic is transparent, verifiable, and executed on L2. ## Staking & Security (Jito Restaking) To become a validator, you must stake \$VRT — this gives you access to validator duties and reward eligibility. Ping uses **Jito Restaking** to secure the L2 ledger and provide extra yield to stakers. Rewards are based on: * Stake size * Network performance * Ping tokenomics and distribution logic > In early phases, validators are directly paid for securing the network. > > If a validator misbehaves and a majority confirms it, **slashing** is applied — burning part of their funds. # City Source: https://docs.pingnetwork.io/proxy/geotarget/city You can target a specific city by using the `city` parameter in your proxy string. This parameter allows you to connect to a proxy located in a specific city.\ You can specify any city in the proxy string. If a city uses a space in its name, replace the space with a dot (e.g., `New York` becomes `new.york`). Make sure to spell the city name in lowercase. If a city is not available our proxy servers will respond with a 412 error code. ### Valid `cc` + `city` examples cc-US-city-los.angeles cc-IT-city-rome cc-TH-city-bangkok cc-JP-city-tokyo cc-AU-city-sydney cc-ES-city-barcelona ## Code example Example: request from **Munich, Germany** (cURL): ```bash curl -x USERNAME-cc-DE-city-munich:PASSWORD@proxy.pingnetwork.io:7776 https://ipinfo.io/json ``` ## Download list of all cities You can download the full list of supported cities here:
Download file
cities.json
# Country Source: https://docs.pingnetwork.io/proxy/geotarget/country You can target a specific country by using the `cc` parameter in your proxy username string. This parameter allows you to connect to a proxy located in a specific country. You can specify any country in the ISO 3166-1 alpha-2 format (e.g., `US` for the United States, `CA` for Canada). ## Code Examples Example: request from Turkey (cURL): ```bash curl -x USERNAME-cc-TR:PASSWORD@proxy.pingnetwork.io:7776 https://ipinfo.io/json ``` Example: request from United States (cURL): ```bash curl -x USERNAME-cc-US:PASSWORD@proxy.pingnetwork.io:7776 https://ipinfo.io/json ``` Example: request from Germany (cURL): ```bash curl -x USERNAME-cc-DE:PASSWORD@proxy.pingnetwork.io:7776 https://ipinfo.io/json ``` ## Parameter Format Country targeting uses the standard proxy endpoint with country parameter in the username: ```text USERNAME-cc-:PASSWORD@proxy.pingnetwork.io:7776 ``` Where `` is the ISO 3166-1 alpha-2 country code. ## Download list of all countries You can download the full list of countries and entry nodes here:
Download file
countries.json
# Region Source: https://docs.pingnetwork.io/proxy/geotarget/region *** You can target a specific region (state) by specifying the `region` in the proxy string. Regions can be things like states, provinces, or territories depending on the country. Valid examples are `california`or `southern.cape`. ### Valid examples region-california region-new\.jersey ## Code example Example: request from **California** (cURL): ```bash curl -x USERNAME-region-california:PASSWORD@proxy.pingnetwork.io:7776 https://ipinfo.io/json ``` ## Download list of regions You can download the full list of supported regions here:
Download file
regions.json
# Location Settings Source: https://docs.pingnetwork.io/proxy/geotarget/residentalproxiesgeo Geo-targeting allows you to specify the geographic location of the proxy you want to use. This can be essential for tasks like localized testing, content access, and more. Below, we’ll explain the key geo-targeting parameters and show you how to use them effectively. Our swiss quality residential proxies have the following geo-targeting parameters available: ## **Geo-targeting Parameters** * **-cc-**: Specify the country of the proxy. * **-city-**: Specify the city of the proxy. * **-region-**: Specify the region of the proxy. * **-continent-**: Specify the continent of the proxy. ### **Notes** * You only need to specify either the country OR the region. # FAQ Source: https://docs.pingnetwork.io/proxy/residential/faqproxies ### Which ports do you use for proxies? We always use the same ports: 7776 for HTTP and 7777 for HTTPS. These ports are fixed for this proxy service and do not change between sessions. ### Is there a limit on the number of simultaneous sessions? There is no limit on the number of simultaneous sessions for the proxy service. You can open as many concurrent connections as your client and network allow. ### Can one port handle multiple geographic locations at the same time? Yes, a single port can handle requests that resolve to different IPs and locations. The port itself is shared while the backend assigns different device IPs per request or session. ### Do I need a session parameter to get different IPs for parallel streams? No, the session parameter is optional and not required to get different IPs for parallel streams. Without sessions, every new request receives a different IP address automatically. ### When should I use the session parameter? Use a session only when you need to keep the same IP address across multiple requests. Sessions pin a consistent IP to a stream so repeated requests look like they come from one device. ### If I run 100 parallel threads without sessions, will they all get different IPs? Yes, 100 parallel threads without sessions will receive different IPs for each request. The system will assign randomized device IPs for each request automatically. ### How often does the IP change if I do not use sessions, and how fast is the change? If you do not use sessions, the IP changes on every new request and this happens instantly. There is no measurable overhead or delay for the IP change in normal operation. ### If an IP drops during an active session, will it get replaced automatically? Yes, if an IP becomes invalid during a session the system will replace it automatically with a valid IP. Your session will continue using the new assigned device IP without extra action. ### Which country codes are valid for geo selection and can countries disappear from the list? All ISO 3166-1 country codes are valid for selection when devices exist there. Countries do not disappear from the code list, but some exotic locations may temporarily lack available devices. ### Is there any performance overhead to changing IPs per request versus using sessions? There is no performance overhead for changing IPs per request; changes occur instantly and transparently. The only difference is whether requests consistently originate from the same device or from random devices. ### Practical recommendation for parallel streams and browser use For parallel browser streams use sessions when you need stable IPs between requests. If you need many unique IPs quickly, omit sessions and rely on automatic per-request rotation. # Getting Started Source: https://docs.pingnetwork.io/proxy/residential/getting-started Our service provides access to a global network of residential proxies, allowing you to make requests from real IP addresses across different locations. ## Overview Ping Residential Proxy Gateway offers: * **Global residential IPs** - Access to genuine residential IP addresses from around the world * **Country-level targeting** - Route requests through specific countries * **Simple integration** - Standard HTTP/HTTPS proxy protocols ## Endpoints We provide two proxy endpoints: * **HTTPS Proxy**: `https://proxy.pingnetwork.io:7777` * **HTTP Proxy**: `http://proxy.pingnetwork.io:7776` ## Authentication All requests require authentication using proxy user credentials. To obtain your credentials, please contact our support team: [support@pingnetwork.io](mailto:support@pingnetwork.io) ## Quick Example Here's a simple example using cURL to make a request through a random residential proxy: ```bash curl -x USERNAME:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain ``` This request will route through a random residential IP address from our global pool. ## Next Steps * Making Requests - Learn about request parameters and advanced usage * Contact support team [support@pingnetwork.io](mailto:support@pingnetwork.io) to obtain your credentials * Review our code examples for your preferred programming language # Making Requests Source: https://docs.pingnetwork.io/proxy/residential/making-requests This guide covers how to make requests through the Ping Residential Proxy Gateway, including parameter configuration and code examples. ## Basic Request Structure All requests follow standard HTTP/HTTPS proxy protocols. You'll need to: 1. Specify the proxy endpoint 2. Provide authentication credentials 3. Make your request to the target URL ## Authentication Authentication is handled through proxy user credentials in the format: ``` USERNAME:PASSWORD ``` To obtain credentials, please contact our support team ([support@pingnetwork.io](mailto:support@pingnetwork.io)). ## Request Parameters You can customize your proxy requests by adding parameters to the username string. Parameters are separated by hyphens (`-`). ### Username Format ``` USERNAME[-parameter-value]...:PASSWORD ``` ### Available Parameters #### Country Code (`cc`) Select a specific country for your proxy request. * **Parameter**: `cc` * **Format**: ISO Alpha-2 country code (case-insensitive) * **Example**: `cc-US` for United States, `cc-GB` for United Kingdom Example username with country selection: ``` USERNAME-cc-US:PASSWORD ``` #### City (`city`) Target a specific city within a country. * **Parameter**: `city` * **Format**: City name in English (case-insensitive) * **Example**: `city-London`, `city-NewYork` #### Region (`region`) Target a specific region or state within a country. * **Parameter**: `region` * **Format**: Region/state name in English (case-insensitive, use dots for spaces: new\.hampshire) * **Example**: `region-california`, `region-new.hampshire` #### Continent (`continent`) Target a specific continent for your proxy request. * **Parameter**: `continent` * **Format**: Continent name (use dots for spaces: north.america) * **Example**: `continent-europe`, `continent-north.america` #### Session ID (`session`) Maintain the same IP address across multiple requests. * **Parameter**: `session` * **Format**: A unique alphanumeric string, 6 to 15 characters long. * **Session Duration**: from 1 up to 120 minutes * **Example**: `session-abc123` #### Session Lifetime (`lifetime`) Specify the duration for a session in minutes. * **Parameter**: `lifetime` * **Format**: Number of minutes (1-120) * **Default**: 40 minutes if not specified * **Example**: `lifetime-60` ### Complete Parameter Example Once all parameters are available, you'll be able to combine them: ``` USERNAME-cc-US-region-California-city-LosAngeles-session-abc123-lifetime-60:PASSWORD ``` ## Code Examples ### Random Proxy (Default) Make a request through a random residential proxy: #### cURL ```bash curl -x USERNAME:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain ``` #### Python (requests) ```python import requests proxies = { 'http': 'http://USERNAME:PASSWORD@proxy.pingnetwork.io:7776', 'https': 'https://USERNAME:PASSWORD@proxy.pingnetwork.io:7777' } response = requests.get('https://ipecho.net/plain', proxies=proxies) print(response.json()) ``` #### Node.js (axios) ```javascript const axios = require('axios'); const HttpsProxyAgent = require('https-proxy-agent'); const proxyUrl = 'http://USERNAME:PASSWORD@proxy.pingnetwork.io:7776'; const agent = new HttpsProxyAgent(proxyUrl); axios.get('https://ipecho.net/plain', { httpsAgent: agent }) .then(response => { console.log(response.data); }) .catch(error => { console.error('Error:', error); }); ``` ### Country-Specific Proxy Route your request through a specific country: #### cURL ```bash curl -x USERNAME-cc-GB:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain ``` #### Python (requests) ```python import requests # Request through UK proxy proxies = { 'http': 'http://USERNAME-cc-GB:PASSWORD@proxy.pingnetwork.io:7776', 'https': 'https://USERNAME-cc-GB:PASSWORD@proxy.pingnetwork.io:7777' } response = requests.get('https://ipecho.net/plain', proxies=proxies) print(response.json()) ``` #### Node.js (axios) ```javascript const axios = require('axios'); const HttpsProxyAgent = require('https-proxy-agent'); // Request through German proxy const proxyUrl = 'http://USERNAME-cc-DE:PASSWORD@proxy.pingnetwork.io:7776'; const agent = new HttpsProxyAgent(proxyUrl); axios.get('https://ipecho.net/plain', { httpsAgent: agent }) .then(response => { console.log(response.data); }) .catch(error => { console.error('Error:', error); }); ``` ## Response Handling The proxy gateway returns the response from your target URL unchanged. Handle responses according to your target API's documentation. ### Error Codes Common proxy-related errors: * **407 Proxy Authentication Required** - Invalid credentials * **429 Too Many Requests** - Rate limit exceeded * **503 Service Unavailable** - No proxies available for the specified parameters ## Best Practices 1. **Use HTTPS endpoint** when possible for better security 2. **Handle errors gracefully** - Implement retry logic for temporary failures 3. **Respect rate limits** - Avoid overwhelming the proxy service 4. **Keep credentials secure** - Never commit credentials to version control ## Need Help? Contact our support team [support@pingnetwork.io](mailto:support@pingnetwork.io) for: * Credential requests * Technical assistance * Feature requests # Sessions Control Source: https://docs.pingnetwork.io/proxy/residential/sessions By default, each request to our proxy server generates a new IP address. However, you can use session parameters to maintain the same IP address for multiple requests. This feature is useful for tasks that require a stable connection, such as web resources with session-based authentication.\ **Session Parameters** We offer the `session` parameter to ensure you keep the same IP for all following requests. ### The`session`parameter * A unique alphanumeric string, 6 to 15 characters long. * Optimized for the highest overall success rate. * May change IP address in favor of stability. * Works with the `lifetime` parameter. When specifying any geo targeting parameters, the first request will use the specified parameters, and all subsequent requests will use the same IP address. If you change the targeting while maintaining the same session, the IP address will remain the same. ### The`lifetime`parameter * Specifies the duration for the `session` in minutes. * Maximum value is 120 minutes. * After the specified time, the IP address will change. * If not specified, the session will last for 40 minutes by default. If you specify a higher `lifetime` value than the maximum allowed, the request will return a 412 error code. ## **Examples** Below are examples of using Sticky sessions in different programming languages: CURL, Python, and JavaScript. ```bash # Using session parameter curl -x USERNAME-session-abc123:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain # Using session with lifetime (60 minutes) curl -x USERNAME-session-abc123-lifetime-60:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain # Session with geo targeting curl -x USERNAME-cc-US-session-abc123:PASSWORD@proxy.pingnetwork.io:7776 https://ipecho.net/plain ``` ```python import requests # Using session parameter proxies = { 'http': 'http://USERNAME-session-abc123:PASSWORD@proxy.pingnetwork.io:7776', 'https': 'https://USERNAME-session-abc123:PASSWORD@proxy.pingnetwork.io:7777' } # Make multiple requests with the same IP for i in range(3): response = requests.get('https://ipecho.net/plain', proxies=proxies) print(f"Request {i+1}: {response.text.strip()}") # Using session with lifetime proxies_with_lifetime = { 'http': 'http://USERNAME-session-xyz789-lifetime-30:PASSWORD@proxy.pingnetwork.io:7776', 'https': 'https://USERNAME-session-xyz789-lifetime-30:PASSWORD@proxy.pingnetwork.io:7777' } response = requests.get('https://ipecho.net/plain', proxies=proxies_with_lifetime) print(f"Session with 30min lifetime: {response.text.strip()}") ``` ```javascript const axios = require('axios'); const HttpsProxyAgent = require('https-proxy-agent'); // Using session parameter const sessionProxyUrl = 'http://USERNAME-session-abc123:PASSWORD@proxy.pingnetwork.io:7776'; const sessionAgent = new HttpsProxyAgent(sessionProxyUrl); // Make multiple requests with the same IP async function testSession() { for (let i = 0; i < 3; i++) { try { const response = await axios.get('https://ipecho.net/plain', { httpsAgent: sessionAgent }); console.log(`Request ${i+1}: ${response.data.trim()}`); } catch (error) { console.error(`Request ${i+1} failed:`, error.message); } } } // Using session with lifetime const lifetimeProxyUrl = 'http://USERNAME-session-xyz789-lifetime-45:PASSWORD@proxy.pingnetwork.io:7776'; const lifetimeAgent = new HttpsProxyAgent(lifetimeProxyUrl); async function testSessionWithLifetime() { try { const response = await axios.get('https://ipecho.net/plain', { httpsAgent: lifetimeAgent }); console.log(`Session with 45min lifetime: ${response.data.trim()}`); } catch (error) { console.error('Session request failed:', error.message); } } testSession(); testSessionWithLifetime(); ``` # Quickstart 🌐 Source: https://docs.pingnetwork.io/quickstart Start with Ping Network Ping Network is a universal bandwidth layer. By utilizing global resources from data centers to smartphones, we offer businesses scalable, affordable networking solutions. ## **Download the App** Start earning Ping Points right away. Available on: ## Join our Community ## Learn more Explore these resources to understand Ping Network better: * Learn why Ping is a universal bandwidth layer How to earn, boost, and track your contribution How the Ping infrastructure works Answers to the most common questions Spotted an issue? Send us the details here Need help? Reach out to the Ping team directly ## Build with us If you want to access Ping’s bandwidth infrastructure, [book a call](https://cal.com/nazar-f/intro-call) with us. In the meantime, check [API docs.](https://docs.pingnetwork.io/Clients/API-overview) # What is Ping Network Source: https://docs.pingnetwork.io/what-is-ping A universal bandwidth layer Ping Network is a universal decentralized bandwidth layer. By utilizing global resources from data centers to smartphones, we offer businesses scalable, affordable networking solutions. With Ping Network, users can passively monetize their Internet connection — all while contributing to a faster, more efficient, and reliable Internet. ## **Understanding the Need for Ping Network** The bandwidth market is fragmented, inefficient, and deeply geo-dependent. Businesses today patch together cloud platforms, dedicated hardware, aggregators, and proxies just to achieve basic global coverage. This fragmentation creates high costs, poor flexibility, and major operational overhead. Cloud providers offer reliable compute, but they aren’t built for bandwidth. Their regional presence is limited. AWS operates in only 34 countries and prices increase significantly with growth. For any bandwidth-heavy workload, costs quickly become unsustainable. On the other hand, managing bare-metal infrastructure across dozens of data centers adds operational complexity. Every expansion requires physical setup, custom contracts, and manual upkeep, a slow and inflexible process that doesn’t scale. Meanwhile, demand is surging. Short-form video is everywhere. AI data scraping requires massive throughput. Real-time apps need low-latency content delivery in every region. But bandwidth, the most geographically bound resource in the stack, remains locked behind outdated infrastructure models. Ping Network changes that. It provides access to bandwidth across 190+ countries through a single API. No contracts. No idle infrastructure. Just dynamic access to a global node pool: from enterprise servers to residential devices. Pricing and incentives adapt in real time. Businesses pay only for what they use. In a \$120B+ market built on legacy systems, Ping is creating a scalable, responsive foundation for the Internet. ## **The Opportunity** Ping Network unlocks next-gen networking by tapping into global bandwidth — from data centers to edge devices. It scales fast, with no setup costs or delivery delays that centralized providers face. ### Why it’s a win for everyone ### Businesses * On demand scalability * Global reach * Instant deployment * Cost efficiency * Versatile use cases * Infra without single points of failure * More reach than cloud ### Contributors * Turn your idle devices into income from phones to bare metal servers Ping makes bandwidth scalable, decentralized, and rewardable. This is how the Internet should work. ## **Business Use Cases** Ping Network infrastructure is built to solve real problems across multiple industries. Here's how it's already helping: * **Data Crawling** Helps AI companies and data services access the web with efficient, compliant, and low-cost scraping using residential IPs for localized and seamless collection. Enables real-time web access for AI agents: powering live data retrieval, dynamic interactions, and continuous learning from the open Internet. * **Content Delivery** Acts as a decentralized alternative to traditional CDNs, delivering faster load times, broader geographic reach, and significantly reduced costs for streaming, media, and digital platforms. * **VPN Routing** VPN services require consistent uptime, high-speed performance, and broad geographic coverage to deliver a seamless user experience. Traditional centralized infrastructure often introduces bottlenecks, limits scalability, and increases operational overhead. With Ping Network, VPN providers gain on-demand access to high-performance bandwidth from a decentralized pool of residential, enterprise, and edge nodes across 190+ countries. This approach eliminates the need for legacy servers, reduces infrastructure costs, and improves overall reliability. By leveraging Ping’s distributed architecture, VPN applications can scale dynamically and maintain stable performance even under high traffic demand. * **Geodata Intelligence** Ping Network provides access to thousands of nodes in over 190 countries, enabling precise, location-specific testing directly from real user environments. Businesses can simulate end-user experiences, detect geoblocking, validate IP geolocation, and verify localized content delivery, all using real residential IPs. This gives teams a reliable, ground-truth view of how their applications perform across global markets. * **Uptime Monitoring** Ping makes it simple to verify uptime, latency, and availability using a globally distributed network of independent nodes. Instead of relying on centralized cloud testers or internal infrastructure, companies can enforce service-level agreements (SLAs) using real-time data from location-aware endpoints, helping detect downtime, ensure performance, and maintain compliance at a global scale. * **Any Bandwidth-Focused Business** Any business relying on scalable bandwidth can benefit from the flexibility and efficiency of Ping Network. Ping Network bridges the gap between legacy infrastructure and the demands of today’s real-time, distributed Internet. It provides businesses the bandwidth and reach they need to scale, and gives users a way to earn by contributing unused capacity.