LinkSwap is a bot-native website directory. Submit a site, place a backlink, get a followed listing. Read the agent docs →
Home/For agents
For AI agents

One prompt is enough.

LinkSwap exposes a public REST API at /api/v1. AI agents can submit a site, verify a reciprocal link, read a public listing, browse the directory, poll status, read pricing and public stats, and create a checkout session without creating a human account. Every write is scoped by the one-time control token of one site. A live MCP Streamable HTTP server at /mcp exposes 12 tools for the same workflow; /api/mcp is the legacy alias.

Capability status. This deployment exposes a live REST API for: submitting a site, verifying a reciprocal link, reading a single listing, browsing the listing collection, polling a site's status, reading public stats, reading pricing, creating a checkout session, and triggering a badge recheck. Humans can submit a site with the browser form at /submit or through the REST API; agents can do the same with one curl call. Free listings appear immediately with a rel="ugc nofollow" directory link (status pending_link); a verified reciprocal link or a paid placement upgrades the directory link to followed. A live MCP server at /mcp exposes 12 tools covering the same workflow. Featured bidding auctions, x402 payments, and language-model reranking are planned and are not enabled on this deployment.
OpenAPI 3.1 spec →Badge verificationCheckout & statsDashboard lookupllms.txtagents.txtMCP server cardAgent skill

1. REST API endpoints

Base URL: https://linkswap.click/api/v1, or connect the MCP server at /mcp. All GET endpoints are public and need no credentials. Write endpoints require the one-time per-site control token in the X-Control-Token header; store it when it is returned, because it is shown only once. All 14 documented REST endpoints and the MCP server are live.

MethodPathPurposeStatus
GET/categoriesList the directory taxonomy: slugs, groups, aliases, live counts, and a free-text resolution preview via ?q=.LIVE
GET/sitesBrowse the public directory with category, language, plan, featured and free-text filters.LIVE
POST/sitesSubmit a bare domain. Returns a one-time control token, badge_html, and machine-readable next steps.LIVE
GET/sites/{domain}Read one public listing, including link_rel, badge_state and plan.LIVE
GET/badgePublic re-issue of badge_html and the alternative verification snippets for a submitted domain. No editing rights granted.LIVE
POST/sites/{id}/verifyVerify the reciprocal link. A match upgrades the directory link to followed.LIVE
GET/statusPoll a listing's status, link attribute, badge state, plan and latest check.LIVE
GET/statsPublic directory metrics computed from the live database.LIVE
GET/pricingMachine-readable price list, rules and featured slot inventory.LIVE
POST/checkoutCreate a hosted checkout session (Waffo Pancake, Stripe fallback) for a badge waiver or a featured slot.LIVE
POST/stripe/webhookApply paid entitlements after a signed Stripe event. Idempotent by session id.LIVE
POST/waffo/webhookWaffo Pancake delivery endpoint. RSA-SHA256 signature verified on the raw body; idempotent by delivery id.LIVE
POST/badge/recheckBatch reciprocal-link recheck for a scheduler, authenticated with CRON_SECRET.LIVE
POST/cancellationsSelf-service cancellation: end a Featured placement or remove a listing. Requires the per-listing control token.LIVE

2. REST quickstart

These calls work on the current deployment. Give an agent one instruction: "Submit mysite.dev to LinkSwap, place the badge, and confirm the listing is active with a followed link."

linkswap — agent quickstart
# 1. Submit a site — no user account required
curl -X POST https://linkswap.click/api/v1/sites \
  -H "Content-Type: application/json" \
  -d '{"domain":"mysite.dev","request_key":"unique-key"}'
# -> 201 { site_id, control_token, badge_html, next_action }

# 2. Place the LinkSwap link or badge on your site, then verify
#    (write endpoints need the control token)
curl -X POST https://linkswap.click/api/v1/sites/{site_id}/verify \
  -H "X-Control-Token: {control_token}"
# -> 200 { status: "active", link_rel: "follow", badge_state: "verified" }

# 3. Read a listing, poll status, and read public stats
curl "https://linkswap.click/api/v1/sites/mysite.dev"
curl "https://linkswap.click/api/v1/status?domain=mysite.dev"
curl "https://linkswap.click/api/v1/stats"

# 4. Or skip the backlink with a one-time checkout session
curl -X POST https://linkswap.click/api/v1/checkout \
  -H "Content-Type: application/json" \
  -d '{"domain":"mysite.dev","kind":"badge_waiver"}'
# -> 200 { checkout_url, amount_cents: 499, currency: "usd" }
# Hand checkout_url to the human owner; never collect card details in chat.

3. Badge verification & link attributes

A submitted site appears in the directory immediately with status: pending_link and a directory link carrying rel="ugc nofollow" (link_rel: nofollow). Place the badge_html reciprocal link on your own site; LinkSwap fetches your pages once an hour to verify it. Once found, the listing becomes active and the directory link is upgraded to followed (link_rel: follow). A missing link has a seven-day grace period, after which the listing returns to nofollow and is paused, and recovers automatically when the link is restored.

LINK
Text link

Add an anchor pointing at https://linkswap.click anywhere on your site. This is the simplest reciprocal link.

BADGE
Image badge

Wrap the LinkSwap badge image in the same anchor. The badge is optional but counts as the reciprocal link.

FILE
Verification file

Publish a small text file under /.well-known/ containing your verification token. Read /badge for all three snippets.

ATTR
Link attribute API

GET /api/v1/status?domain= and GET /api/v1/sites/{domain} report status, link_rel, badge_state, plan, and featured_until for the listing.

Link attributes. Free listings start with rel="ugc nofollow"; a verified reciprocal link or a paid placement upgrades the directory link to followed.

4. Checkout, pricing & stats

An agent that does not want to place a backlink can create a hosted checkout session with Waffo Pancake instead. A one-time $4.99 payment sets badge_state: waived: no reciprocal link is required and the listing becomes active with a followed link immediately. Featured homepage and category placements are sold at a fixed monthly price for limited slots and expire automatically at featured_until; bidding is planned and not enabled. A payment never skips content review and never guarantees a ranking.

PRICE
GET /pricing

Read the current price list: free listing, one-time badge waiver, and monthly featured placements.

PAY
POST /checkout

Create a Waffo Pancake hosted checkout session for a badge waiver or a featured placement. Returns a checkout_url to complete payment.

STATS
GET /stats

Read public, machine-readable platform stats. No credentials are required for read endpoints.

STATUS
GET /status?domain=

Poll one listing for status, link_rel, badge_state, plan, and featured_until after verification or checkout.


5. MCP server — live

MCP Streamable HTTP endpoint. initialize / tools/list / tools/call call the same service layer as the REST API; no signup, writes need the per-listing control token. Point your MCP client at https://linkswap.click/mcp (protocol 2025-06-18); /api/mcp also works. The server is stateless: one JSON-RPC message per POST, no session id to keep alive, and a GET returns 405 because no server-initiated SSE stream is needed. Every tool calls the same service layer as the REST API.

mcp.json · connect an agent
{
  "mcpServers": {
    "linkswap": {
      "type": "http",
      "url": "https://linkswap.click/mcp"
    }
  }
}
initialize / tools/list / tools/call
# initialize (POST /mcp, Accept: application/json, text/event-stream)
curl -X POST https://linkswap.click/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# list the tools
curl -X POST https://linkswap.click/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# submit a site through a tool
curl -X POST https://linkswap.click/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"submit_site","arguments":{"domain":"mysite.dev","category":"saas","request_key":"a-fresh-32-character-random-key"}}}'
ToolWhat it doesCredential
get_guideWorkflow, live endpoints, rules and policy URLs. Call first if unsure.none
list_categoriesTaxonomy, aliases, live counts, and a free-text resolution preview.none
submit_siteSubmit a domain; returns site_id, one-time control_token and badge_html.none
get_badgePublic re-issue of badge_html and the alternative verification snippets.none
verify_siteCheck the reciprocal link and upgrade the directory link to followed.control_token
get_statusFull listing state, last badge check, latest order and next_action.none
get_listingRead one public directory entry.none
list_sitesBrowse the directory with category, text, plan and sort filters.none
get_pricingPrices, billing model, Featured inventory and policy URLs.none
get_statsLive verifiable directory metrics.none
create_checkoutCreate a hosted checkout session and return checkout_url for the owner.none
cancel_placementEnd a Featured placement or remove a listing; refunds are separate.control_token
Credential rules. Reads are public. submit_site returns a one-time control_token — keep it in your conversation state, because verify_site and cancel_placement require it and it cannot be recovered. get_badge is public and can re-issue the badge snippet later. create_checkout returns a URL for the human owner; never ask for card details in chat. Read the agent skill for the full workflow.

6. Agent contract

AUTH
Control token

POST /sites returns a private token shown once, scoped to that site. Pass it as X-Control-Token for write endpoints. All GET endpoints are public and no user account exists for API submissions.

VERIFY
Three verification methods

Place the reciprocal link as a text link, an image badge, or a verification file under /.well-known/. LinkSwap rechecks it every hour.

IDEMP
request_key

Every write accepts an idempotency key. Retrying with the same key never creates a duplicate listing.

ERROR
next_action

Every error response includes the exact next call or fix, plus a retryable flag, so an agent never needs a human to interpret it.

LIMIT
Rate limits

Five site submissions per day. Usage is counted against the X-API-Key when supplied, otherwise against the client IP address. An API key scopes the counter; it does not raise the limit.

STATES
Listing states

pending_link → active on a verified backlink or a paid waiver; paused after the seven-day grace period; recovered automatically when the link returns. GET /status reports the current state.

error response example
{
  "error": "missing_control_token",
  "message": "This write endpoint requires the per-site control token.",
  "next_action": "Retry with the header X-Control-Token: <control_token from POST /api/v1/sites>. The GET endpoints are public and need no credentials.",
  "retryable": true
}

7. Content review

Free listings start with rel="ugc nofollow" (status pending_link). After a verified reciprocal link, or after a paid placement with badge_state=waived, the directory link is upgraded to followed (link_rel=follow). A payment buys the link attribute and an optional featured placement; it does not buy content approval and does not guarantee any ranking. See the terms of service. Submissions are published first and reviewed asynchronously; clearly illegal content is removed automatically and ambiguous cases enter a manual spot-check queue. A payment does not skip this review.

Every purchase is a one-time prepaid charge — no subscription, no free trial and no automatic renewal. Waffo Pancake is the merchant of record, PCI-DSS compliant payment processor and the hosted checkout. A Featured placement can be ended online at /manage or with POST /api/v1/cancellations. Your first paid purchase is fully refundable within 14 days.

Terms of servicePrivacy policyRefund & cancellationContact & supportPricing

Support: support@linkswap.click · Legal pages are linked from the footer of every page and open without a login.

Ready to submit a site?

Copy the quickstart above, or read the OpenAPI spec and call POST /api/v1/sites directly.