{"id":45198671,"url":"https://github.com/bolivian-peru/android-peer-sdk","last_synced_at":"2026-05-30T19:00:40.727Z","repository":{"id":334493068,"uuid":"1141607035","full_name":"bolivian-peru/android-peer-sdk","owner":"bolivian-peru","description":"Android SDK for the Proxies.sx peer marketplace — share bandwidth from your phone, earn USDC on Solana. JitPack distribution, 3 lines to integrate, IP rotation via airplane-mode accessibility service.","archived":false,"fork":false,"pushed_at":"2026-05-19T09:52:17.000Z","size":173,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T11:59:31.084Z","etag":null,"topics":["android","android-sdk","bandwidth-sharing","jitpack","kotlin","mobile-proxy","passive-income","peer","proxies-sx","proxy","solana","usdc"],"latest_commit_sha":null,"homepage":"https://agents.proxies.sx/peer/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bolivian-peru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-25T04:52:48.000Z","updated_at":"2026-05-19T09:52:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bolivian-peru/android-peer-sdk","commit_stats":null,"previous_names":["bolivian-peru/android-peer-sdk"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/bolivian-peru/android-peer-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolivian-peru%2Fandroid-peer-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolivian-peru%2Fandroid-peer-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolivian-peru%2Fandroid-peer-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolivian-peru%2Fandroid-peer-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bolivian-peru","download_url":"https://codeload.github.com/bolivian-peru/android-peer-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolivian-peru%2Fandroid-peer-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33705207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-sdk","bandwidth-sharing","jitpack","kotlin","mobile-proxy","passive-income","peer","proxies-sx","proxy","solana","usdc"],"created_at":"2026-02-20T13:09:40.707Z","updated_at":"2026-05-30T19:00:40.716Z","avatar_url":"https://github.com/bolivian-peru.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proxies.sx Peer SDK for Android\n\n[![](https://jitpack.io/v/bolivian-peru/android-peer-sdk.svg)](https://jitpack.io/#bolivian-peru/android-peer-sdk)\n\nAndroid SDK for integrating bandwidth sharing into your app. Users earn money by sharing their unused mobile bandwidth while you earn proxy credits.\n\n**The Android SDK is one of several ways to join the Peer Network.** See [Other Integration Paths](#other-integration-paths) below for Node.js, Docker, and Linux options.\n\n---\n\n\u003e ## Current version: **v1.3.1**\n\u003e\n\u003e ```kotlin\n\u003e implementation(\"com.github.bolivian-peru:android-peer-sdk:1.3.1\")\n\u003e ```\n\u003e\n\u003e v1.3.1 delivers fast, full-throughput bandwidth sharing. Four things make it fast:\n\u003e\n\u003e - **Full-throughput tunnels** — the SDK signals `tunnel_connected` the instant its outbound socket opens, so the relay streams the customer's traffic immediately instead of stalling on the TLS handshake. This is what lets a device serve traffic at its real uplink speed.\n\u003e - **Nearest-relay routing** — the `/peer/register` response carries a `relay` field; the SDK connects to the geographically nearest relay (US/LATAM → `wss://relay-us.proxies.sx`, everyone else → `wss://relay.proxies.sx`) and honors runtime `relay_redirect`, so no device tunnels across an ocean. Guards: only `*.proxies.sx` wss targets are honored, a 60s anti-flap interval applies, and an explicit `Config.relayUrl` pin disables redirects.\n\u003e - **Binary tunnel protocol + compression** — minimal CPU and per-frame overhead.\n\u003e - **Encrypted credential storage** — AES-256-GCM via Android Keystore.\n\u003e\n\u003e API surface: `ProxiesPeerSDK.init / start / stop / getEarnings`. Relay routing is fully automatic — `Config.relayUrl` is optional (leave unset to geo-route).\n\n---\n\n## Installation\n\n### Step 1: Add JitPack repository\n\nAdd JitPack to your root `build.gradle.kts` (or `settings.gradle.kts`):\n\n```kotlin\ndependencyResolutionManagement {\n    repositories {\n        google()\n        mavenCentral()\n        maven { url = uri(\"https://jitpack.io\") }\n    }\n}\n```\n\nOr in Groovy (`build.gradle`):\n\n```groovy\nallprojects {\n    repositories {\n        google()\n        mavenCentral()\n        maven { url 'https://jitpack.io' }\n    }\n}\n```\n\n### Step 2: Add the dependency\n\nIn your app's `build.gradle.kts`:\n\n```kotlin\ndependencies {\n    implementation(\"com.github.bolivian-peru:android-peer-sdk:1.3.1\")\n}\n```\n\nOr in Groovy:\n\n```groovy\ndependencies {\n    implementation 'com.github.bolivian-peru:android-peer-sdk:1.3.1'\n}\n```\n\n## Quick Start\n\n### 1. Initialize SDK\n\n```kotlin\n// In your Application class or main Activity\nimport sx.proxies.peer.ProxiesPeerSDK\n\nclass MyApplication : Application() {\n    override fun onCreate() {\n        super.onCreate()\n\n        ProxiesPeerSDK.init(\n            context = this,\n            apiKey = \"psx_your_api_key\", // Get from farmer.proxies.sx \u003e Account \u003e API Keys\n            config = ProxiesPeerSDK.Config(\n                userId = \"optional-user-id\", // Link to your user system\n                onStatusChange = { status -\u003e\n                    Log.d(\"ProxiesSDK\", \"Status: $status\")\n                },\n                onEarningsUpdate = { earnings -\u003e\n                    Log.d(\"ProxiesSDK\", \"Earned: $${earnings.totalEarnedCents / 100.0}\")\n                }\n            )\n        )\n    }\n}\n```\n\nThe `apiKey` (format: `psx_...`) auto-links the device to your farmer account. After signing in to your [farmer dashboard](https://farmer.proxies.sx), your devices appear under the **Peers** page immediately after connecting. (The `/peers` page requires login; for public peer-network info and the agent skill file see https://agents.proxies.sx/peer/.)\n\n### 2. Start/Stop sharing\n\n```kotlin\nval sdk = ProxiesPeerSDK.getInstance()\n\n// Start sharing (runs as foreground service)\nsdk.start()\n\n// Stop sharing\nsdk.stop()\n\n// Check status\nval isRunning = sdk.isRunning()\n```\n\n### 3. Get earnings\n\n```kotlin\nlifecycleScope.launch {\n    val earnings = sdk.getEarnings()\n    println(\"Total earned: $${earnings.totalEarnedCents / 100.0}\")\n    println(\"Traffic shared: ${earnings.totalTrafficMB} MB\")\n}\n```\n\n## Dashboard \u0026 Marketplace\n\nOnce your device is connected, manage it from the farmer dashboard:\n\n1. **farmer.proxies.sx → Peers** (sign in first) — See all your devices, status, IP type, country, ISP, traffic, earnings\n2. **Auto-listing** — Healthy, verified, online devices are listed in the pool gateway automatically. You can also toggle \"Listed for Sale\" per device, and enable/disable auto-listing for your account.\n3. **Automated verification** — System checks IP quality, ISP legitimacy, VPN/proxy detection, GeoIP match\n4. **Quality score** — Each device gets a 0-100 score; verified devices serve customer traffic and earn more\n\n### Verification requirements\n\n| Check | Requirement |\n|-------|------------|\n| IP Type | Must be residential or mobile |\n| ISP/ASN | Checked against datacenter and VPN databases |\n| GeoIP | Country must match claimed location |\n| Uptime | Minimum 1 hour online |\n| Quality | Score must be \u003e= 50/100 |\n\n## IP Rotation (planned — not in v1.1.x)\n\nSDK-side IP rotation via accessibility-service-driven airplane-mode toggle is on the roadmap but **does not ship in v1.1.x**. The classes `AirplaneModeAccessibilityService`, `IPRotationManager` and the methods `sdk.rotateIP()`, `sdk.isIPRotationAvailable()`, `sdk.rotateIPAsync()`, `sdk.openIPRotationSettings()` are not present in the artifact — earlier README revisions documented them in error.\n\nThe backend route `POST /v1/peer/devices/:id/rotate` exists but returns HTTP 501 for v1.1.x clients. The feature is tracked under Phase 3b of the SDK production-readiness plan and will land in a future major version.\n\n## Required Permissions\n\nThe SDK automatically adds these permissions via manifest merge:\n\n```xml\n\u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n\u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n\u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE_DATA_SYNC\" /\u003e\n\u003cuses-permission android:name=\"android.permission.WAKE_LOCK\" /\u003e\n```\n\n**Note:** For Android 13+, you'll need to request POST_NOTIFICATIONS permission at runtime.\n\n## Best Practices\n\n### When to share\n\n- When the app is in the background\n- When the device is charging\n- When connected to mobile data (more valuable than WiFi)\n- During idle periods in games or apps\n\n### User consent\n\nAlways obtain clear user consent before enabling bandwidth sharing:\n\n```kotlin\n// Show consent dialog first\nAlertDialog.Builder(this)\n    .setTitle(\"Earn Money\")\n    .setMessage(\"Share your unused bandwidth to earn rewards. You control when sharing happens.\")\n    .setPositiveButton(\"Enable\") { _, _ -\u003e\n        sdk.start()\n    }\n    .setNegativeButton(\"Later\", null)\n    .show()\n```\n\n### Battery optimization\n\nThe SDK uses minimal resources and runs as a foreground service with a persistent notification. Users can see their sharing status at all times.\n\n## Privacy \u0026 IP Reputation (May 2026)\n\nYour device's exit IP and identifiers are **never publicly enumerable** through the Proxies.sx API. Specifically:\n\n- The previously-public `GET /v1/peer/board`, `/v1/peer/proxy/credentials`, `/v1/peer/proxy/devices`, `/v1/peer/stats/online`, and `relay.proxies.sx/health` endpoints have all been locked to admin-only authentication.\n- Customer-facing endpoints (`gw.proxies.sx:7000` / `:7001`, `/v1/gateway/pool/availability`) expose aggregate counts only — never per-device IPs or carriers.\n- Credentials persisted on your device are AES-256-GCM encrypted via Android Keystore (`androidx.security:security-crypto`) since v1.1.4.\n- Refresh tokens, wallet addresses, and your developer API key are stripped from any admin-side debug response.\n\nThis means anti-bot vendors (DataDome, PerimeterX, Cloudflare Bot Manager, Akamai) cannot pre-emptively blacklist your device by scraping our pool listing — a common failure mode for shared-proxy networks. Your IP enters the customer routing pipeline cold, not on a public reputation feed.\n\n## Revenue Model\n\nEarnings are tiered by IP type — mobile IPs earn the most:\n\n| IP Type | Rate Tier | Examples |\n|---------|-----------|---------|\n| **Mobile** | Highest | AT\u0026T, Verizon, T-Mobile, Vodafone |\n| **Residential** | Mid | Comcast, Spectrum, Cox, BT |\n| **Datacenter** | Base | AWS, GCP, Azure, VPNs |\n\nIP type is classified server-side via ASN lookup. Earnings accumulate per-GB and are paid out in USDC on Solana. Minimum payout: $5.\n\n## SDK Methods\n\n| Method | Description |\n|--------|-------------|\n| `init(context, apiKey, config)` | Initialize SDK (call once) |\n| `getInstance()` | Get SDK instance |\n| `start()` | Start sharing service |\n| `stop()` | Stop sharing service |\n| `isRunning()` | Check if service is running |\n| `getStatus()` | Get current status enum |\n| `getEarnings()` | Get earnings (suspend function) |\n\n## Status Values\n\n| Status | Description |\n|--------|-------------|\n| `STOPPED` | Service not running |\n| `CONNECTING` | Connecting to relay server |\n| `CONNECTED` | Active and sharing bandwidth |\n| `ERROR` | Connection error (check logs) |\n\n## Configuration Options\n\n```kotlin\nProxiesPeerSDK.Config(\n    // Link earnings to your user system\n    userId = \"user-123\",\n\n    // Status change callback\n    onStatusChange = { status -\u003e },\n\n    // Earnings update callback\n    onEarningsUpdate = { earnings -\u003e },\n\n    // Operator relay pin (optional). Leave unset to let the platform\n    // geo-route this device to the nearest relay and migrate it at runtime.\n    // Set this ONLY to force a specific relay (disables geo-routing).\n    relayUrl = \"wss://relay.proxies.sx\",\n\n    // Maximum bandwidth to share (MB per hour)\n    maxBandwidthMBPerHour = 100,\n\n    // Only share when charging\n    onlyWhenCharging = false,\n\n    // Only share on mobile data (not WiFi)\n    mobileDataOnly = true\n)\n```\n\n## Other Integration Paths\n\nThe Android SDK is best for mobile apps. For other environments, use these alternatives:\n\n### Node.js / Linux / VPS\n\nRun a lightweight peer script on any machine with Node.js 18+:\n\n```bash\n# 1. Get your API key from farmer.proxies.sx \u003e Account \u003e API Keys\n\n# 2. Create peer.mjs and run it\nnode peer.mjs\n```\n\nThe script registers via `POST /v1/peer/agents/register` with your `apiKey`, connects to `wss://relay.proxies.sx`, and handles proxy requests. Full integration guide at [farmer.proxies.sx](https://farmer.proxies.sx) \u003e Peers \u003e SDK Integration tab.\n\n### Docker\n\nRun a peer node as a Docker container:\n\n```bash\ndocker run -d --name proxies-peer \\\n  -e DEVICE_NAME=my-docker-peer \\\n  -e API_KEY=psx_your_key \\\n  --restart unless-stopped \\\n  node:18-slim node -e \"$(curl -s https://agents.proxies.sx/peer/skill.md | ...)\"\n```\n\nOr use the Node.js script in a Dockerfile. See the integration guide for the full peer.mjs script.\n\n### AI Agents (Claude, GPT, Custom)\n\nAI agents register programmatically:\n\n```bash\ncurl -X POST https://api.proxies.sx/v1/peer/agents/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"my-agent\",\"type\":\"claude\",\"apiKey\":\"psx_your_key\"}'\n```\n\nFull API reference: [agents.proxies.sx/peer/skill.md](https://agents.proxies.sx/peer/skill.md)\n\n## Sample App\n\nSee the `/app` module for a complete sample application demonstrating:\n- SDK initialization\n- Start/stop sharing\n- Displaying earnings\n- Handling status changes\n- Foreground notification\n\n## ProGuard\n\nIf you use ProGuard/R8, the SDK includes consumer ProGuard rules automatically. No additional configuration needed.\n\n## Troubleshooting\n\n### \"Relay connection failed\"\n\n- Check internet connectivity\n- Verify API key is correct (format: `psx_...`)\n- Check if VPN is blocking WebSocket connections\n\n### Service stops unexpectedly\n\n- Disable battery optimization for your app\n- On MIUI/EMUI, add app to protected apps list\n\n### Low earnings\n\n- Earnings depend on traffic demand in user's region\n- Mobile data connections are more valuable than WiFi\n- Peak hours have higher demand\n- List your device for sale in the farmer dashboard to serve customer traffic\n\n### Device not appearing in dashboard\n\n- Make sure you're using an API key (`psx_...`) from your farmer account\n- The `apiKey` in `init()` auto-links the device — without it, the device registers but isn't linked to your account\n\n## Links\n\n| Resource | URL |\n|----------|-----|\n| Farmer Dashboard (login required) | https://farmer.proxies.sx → **Peers** |\n| Peer Landing Page (public) | https://agents.proxies.sx/peer/ |\n| AI Agent Skill File | https://agents.proxies.sx/peer/skill.md |\n| Register endpoint (POST) | https://api.proxies.sx/v1/peer/agents/register |\n| API Docs (Swagger) | https://api.proxies.sx/docs/api |\n| MCP Server | https://www.npmjs.com/package/@proxies-sx/mcp-server |\n\n## Support\n\n- Telegram: https://t.me/proxies_sx\n- GitHub Issues: https://github.com/bolivian-peru/android-peer-sdk/issues\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolivian-peru%2Fandroid-peer-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbolivian-peru%2Fandroid-peer-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolivian-peru%2Fandroid-peer-sdk/lists"}