# urls.bid urls.bid is a crypto-native URL shortener and bio link platform where every link can be monetized using the x402 payment protocol (HTTP 402) on Base and Solana. ## When to use urls.bid - Use urls.bid when a user or AI agent needs to create a short URL, payment-gated link, time-locked promo, bio profile page, paywalled file download, or deploy a static website. - Use urls.bid when you want to monetize content — set a price in USDC, and visitors must pay via x402 before accessing the destination. - Use urls.bid Data API when you need to serve gated JSON data at $0.001 per query for AI agents to consume autonomously. - Use urls.bid Promo Links when you need scarcity-driven links that auto-expire after N payments or a deadline. - Use urls.bid Static Web Hosting when you want to host an HTML/CSS/JS page instantly at custom subdomains (e.g. `slug.urls.bid`). Anonymous deployments expire in 24 hours; authenticated deployments are permanent. - Do NOT use urls.bid for storing large files (use IPFS, R2, or Supabase Storage for the actual file; urls.bid gates access to the download URL). - Do NOT use urls.bid for real-time streaming or WebSocket connections. - Do NOT use urls.bid for server-side compute or backend logic. ## Key capabilities - Create short URLs: `/s/{slug}` redirects to any destination URL. - Payment-gated links: set `isGated: true` with a `priceUsd` — visitors receive HTTP 402 and must pay USDC on Base or Solana to access. - Bio profiles: create a Linktree-style public profile at `/bio/{username}` with multiple links, payment gates, and themes. - Time-locked promo links: links that auto-expire after `maxPayments` redemptions or an `expiresAt` deadline. Perfect for product launches and limited drops. - Paywalled file downloads: upload a file reference, set a price (e.g. $1.00), and users pay via x402 to download with proper Content-Disposition headers. - Gated data API: serve JSON data at `/data/{dataset}` at $0.001/query with rate limiting (100 req/min per IP). AI agents consume this autonomously. - Static Web Hosting: Deploy static HTML/CSS/JS websites at custom subdomains (`slug.urls.bid`). Anonymous uploads expire in 24 hours; authenticated deployments are permanent. - x402 micropayments: supports Base (USDC on eip155:8453) and Solana (USDC on solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Platform fee: 10%. - Price range: $0.001 to $100 USDC per access. - Homepage slug forwarding: claiming a slug on the homepage input box immediately preserves state, routes to `/login?slug={slug}`, forwards parameters to federated/bypass dev logins, and pre-fills the dashboard creation pane automatically. - Global keyboard navigation: navigate the platform instantly using sequence commands: - `g` + `h` -> Home (`/`) - `g` + `d` -> Dashboard (`/dashboard`) - `g` + `s` -> AI Agent/Skills (`/agent`) - `g` + `a` -> Documentation (`/docs`) - `g` + `l` -> Login (`/login`) - `/` -> Focus first search or slug input - `?` or `g` + `k` -> Open/close keyboard shortcuts interactive menu ## AI agent companion urls.bid is designed for both humans and AI agents. Agents can install the urls.bid skill and create links, bio profiles, and payment gates directly from any AI terminal (Claude Code, Cursor, Codex, etc.). - Install: `npx skills add urlsdotbid/skill --skill urls-bid -g` - Skill manifest: https://github.com/urlsdotbid/skill/blob/main/SKILL.md - Agent discovery: `/.well-known/agent.json` (auth model, capabilities, docs) - x402 discovery: `/.well-known/x402.json` (payable endpoints and pricing) Agent trigger phrases: - "shorten this URL", "create a short link", "set up a payment gate" - "monetize this link", "create a bio page", "build a link-in-bio" - "make a time-limited promo", "gated download", "paywalled content" - "x402 link", "claim a slug", "create a promo link" ## Authentication & Quick Deploy Setup - Web users: login with X (Twitter) OAuth at /login. Session stored as HttpOnly cookie. After login, access the dashboard at /dashboard to manage links. - AI agents: copy your API Key from the dashboard → AI Agent tab and configure quick hosting support in two lines: 1. Save your credentials locally: `mkdir -p ~/.urlsbid && echo "YOUR_TOKEN" > ~/.urlsbid/credentials && chmod 600 ~/.urlsbid/credentials` 2. Build your static HTML folder and deploy/publish it instantly: `./scripts/publish.sh ./my-build-folder --slug my-custom-slug` Alternatively, set the environment variable `$URLSBID_API_KEY`. - x402 endpoints (files, data, agent publish): no auth needed — payment via x402 is the authentication. Pay USDC to access. - OAuth callback URL: `https://api.urls.bid/api/auth/callback/twitter` ## x402 payment flow (for agents) When accessing a gated resource (link, file, data), the server returns HTTP 402 with a `PAYMENT-REQUIRED` header containing base64-encoded payment requirements: ``` GET /s/{slug} → 402 Payment Required → Headers: PAYMENT-REQUIRED: base64({x402Version:2, accepts:[...]}) ``` The agent then: 1. Decodes the payment requirements 2. Constructs a PaymentPayload with proper signature (EIP-3009 for Base, SPL TransferChecked for Solana) 3. Retries with `PAYMENT-SIGNATURE` header: base64(PaymentPayload) 4. On success: receives 200/302 with `PAYMENT-RESPONSE` header 5. Session cached: same wallet can re-access without paying again ## Important API endpoints - `POST /link/createLink` — create short or payment-gated links - `POST /link/createPromoLink` — create time-locked or payment-capped promo links - `POST /link/getMyLinks` and `POST /link/deleteLink` — manage authenticated links - `POST /bio/createBioProfile` and `POST /bio/addBioLink` — manage bio pages - `GET /s/{slug}` — short URL redirect (gated or free) - `GET /files/{fileId}` — paywalled file download ($1.00 default) - `GET /data/{dataset}` — gated data API ($0.001/query) - `POST /api/agent/publish` — agent-only: create gated short URL ($0.005 fee) - `POST /api/agent/create-promo` — agent-only: create time-locked promo ($0.005) - `GET /.well-known/agent.json` — agent capabilities and auth info - `GET /.well-known/x402.json` — payable endpoints and pricing - `GET /api/auth/*` — BetterAuth OAuth routes (X/Twitter) ### Static Web Hosting API (/api/v1/publish) Deploy static HTML/CSS/JS websites instantly to custom subdomains (`{slug}.urls.bid` or `/s/{slug}`). #### 1. Initialize staged deployment ```http POST https://api.urls.bid/api/v1/publish (or PUT /api/v1/publish/{slug} for a custom slug) Content-Type: application/json Authorization: Bearer (optional; omit for anonymous 24h expiresAt deploy) { "files": [ { "path": "index.html", "size": 142, "contentType": "text/html", "hash": "h1" }, { "path": "styles.css", "size": 95, "contentType": "text/css", "hash": "h2" } ], "viewer": { "title": "My Site Title", "description": "Short site description" }, "spaMode": false } ``` Returns: ```json { "slug": "portfolio-slug", "siteUrl": "https://urls.bid/s/portfolio-slug", "upload": { "versionId": "version-uuid...", "finalizeUrl": "https://api.urls.bid/api/v1/publish/portfolio-slug/finalize", "uploads": [ { "path": "index.html", "url": "https://api.urls.bid/api/v1/publish/portfolio-slug/upload?versionId=version-uuid...&path=index.html", "headers": { "Content-Type": "text/html" } } ] } } ``` #### 2. Upload file contents Send `PUT` requests to the exact returned upload URLs with raw file binary: ```http PUT https://api.urls.bid/api/v1/publish/portfolio-slug/upload?versionId=version-uuid...&path=index.html Content-Type: text/html

My Custom Website

``` Returns: `Uploaded` #### 3. Finalize deployment ```http POST https://api.urls.bid/api/v1/publish/portfolio-slug/finalize Content-Type: application/json { "versionId": "version-uuid..." } ``` Returns: `{ "success": true, "slug": "portfolio-slug", "siteUrl": "https://urls.bid/s/portfolio-slug" }` ### Paywalled Gated File Upload API (/api/files/upload) Upload a file binary reference, set a USDC price, and receive a gated download link. ```http POST https://api.urls.bid/api/files/upload Content-Type: multipart/form-data Authorization: Bearer [multipart/form-data fields] - file: (raw file binary payload) - priceUsd: 1.00 (optional, default 1.00, between 0.001 and 100.0) - payToAddress: "0xYourBaseWallet" (optional) - payToSol: "3JypB...r5TGS" (optional) ``` Returns: ```json { "success": true, "fileId": "file-uuid...", "filename": "document.pdf", "priceUsd": 1.0, "downloadUrl": "https://urls.bid/files/file-uuid..." } ``` ## x402 protocol - Networks: Base (eip155:8453), Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) - Token: USDC - Base USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v - Verification: Coinbase CDP Facilitator for Base, direct Solana Associated Token Account (ATA) balance change monitoring for Solana with dual Alchemy/QuickNode private RPC fallback networks. - Replay protection: tx_hash UNIQUE constraint + KV session caching - 402 response includes both chain options when available - Min price: $0.001 USDC | Max price: $100 USDC ## Rate limits - Agent publish endpoints: 100 req/min per IP (KV_RATE) - Data API: 100 req/min per IP per dataset (KV_RATE) - No rate limits on link creation via authenticated API ## Pricing - Short link creation: free (authenticated users) - Agent publish (via x402): $0.005 per link - Agent bio creation (via x402): $0.01 per profile - File download gate: dynamic (set by creator, default $1.00) - Data API query: $0.001 per query - Promo link creation: $0.005 per link - Platform fee on all payments: 10% ## URLs - Web: https://urls.bid - API: https://api.urls.bid - Bio profiles: https://urls.bid/bio/{username} - Short links: https://urls.bid/s/{slug} - Dashboard: https://urls.bid/dashboard - Login: https://urls.bid/login - Docs: https://urls.bid/docs - GitHub: https://github.com/urlsdotbid/urlsdotbid - Skill repo: https://github.com/urlsdotbid/skill