Documentation

Authentication

urls.bid uses X (Twitter) OAuth for user authentication and API keys for programmatic access. To authenticate API requests, include your API key in the Authorization header.

Authorization: Bearer ub_live_xxxxxxxxxxxxxxxxx

Create a new short link. Optionally make it a gated (paid) link by providing a price.

{
  "destinationUrl": "https://example.com/my-long-url",
  "customSlug": "my-custom-slug", // optional
  "isGated": true,
  "priceUsd": 1.50,
  "payToAddress": "0xYourBaseWallet",
  "payToSol": "3JypB...r5TGS",
  "acceptedChains": ["base", "solana"]
}

{
  "slug": "my-custom-slug",
  "shortUrl": "https://urls.bid/my-custom-slug"
}

Retrieve a list of all your created links.

[
  {
    "id": "link_123",
    "slug": "my-custom-slug",
    "destUrl": "https://example.com/my-long-url",
    "clicks": 42,
    "revenue": 15.50
  }
]

Get metadata details for a specific link by its slug (public GET endpoint).

Update a link's destination URL or price.

Delete a link permanently.

Get click analytics and revenue data for a link.

Create a promotional link with special tracking.

Create your bio profile.

Get your own bio profile details.

Get a public bio profile.

Add a new link to your bio profile.

Update a bio link.

Remove a link from your bio.

Reorder the links on your bio profile.

Resolve a short link. Returns 402 Payment Required if the link is gated.

Access a gated file.

Query a gated dataset.

Agent-specific API routes with built-in x402 support.

Well-known Endpoints

Standardized endpoints for agent discovery and protocol support.

Error Codes

Rate Limits

API requests are limited to 100 requests per minute per IP address, and 1000 requests per hour per API key. If you exceed these limits, you will receive a 429 Too Many Requests response.