{"openapi":"3.1.0","info":{"title":"URLGate","version":"2.0.0-preview","description":"Pay-to-open short links. Humans and agents create links that charge USDC via x402 v2 on open. Sign in with SIWE (/api/v2/auth/*) or send a SIGN-IN-WITH-X header. Agents: start with GET /api/v2/agents/get-started (MCP get_started).","contact":{"name":"URLGate","email":"hello@urlgate.xyz","url":"https://urlgate.xyz/terms.html#changes"},"x-guidance":"GET /{code} returns 402 with a PAYMENT-REQUIRED header. Opening a paid link takes TWO signatures in one retry: PAYMENT-SIGNATURE (an accepts[] entry, to the creator) + PAYMENT-SIGNATURE-FEE (the extensions[\"platform-fee\"].accepts[] entry on the same network, to URLGate), same wallet; without the fee leg the request is refused (fee_leg_missing) before anything is charged. To create a link, POST /api/urlgate/agent/create: signed in (Bearer / SIGN-IN-WITH-X) or with an agent key (Bearer ugk_…) it is FREE within the daily quota (10/day, 100 with Premium, 3/day for new wallets); anonymous or over quota it costs the creation fee (one signature); every limit error carries nextSteps. Start with GET /api/v2/agents/get-started. Test your client first, free and verify-only: POST /api/v2/payments/compat-check (MCP payment_compat_check). The preview testnet test link REQUIRES a wallet with Base Sepolia testnet + test USDC. If your wallet can't use testnet, follow the production path: run payment_compat_check on production (verify-only, no funds move) and, if you meet the two-signature requirements, proceed with the real paid tools.","x-agent-pricing":{"getStarted":"/api/v2/agents/get-started","pricing":"/api/v2/pricing","mcpTools":["get_started","pricing_and_limits"],"agentsPage":"/agents","guide":"/agents/guide","paths":["own_wallet","agent_key","pay_per_link"],"freeDailyQuota":{"free":10,"premium":100,"newWallet":3,"newWalletHours":24,"resets":"00:00 UTC"},"agentFee":"0.01"},"x-compat-check":{"path":"/api/v2/payments/compat-check","mcpTool":"payment_compat_check","verifyOnly":true,"requirement":"The preview testnet test link REQUIRES a wallet with Base Sepolia testnet + test USDC.","fallback":"If your wallet can't use testnet, follow the production path: run payment_compat_check on production (verify-only, no funds move) and, if you meet the two-signature requirements, proceed with the real paid tools.","paths":{"testnet":["Use a wallet on Base Sepolia (eip155:84532) holding test USDC (e.g. faucet.circle.com). Only signatures are needed, no gas.","Call payment_compat_check on the preview testnet deployment (urlgate-preview) without payment: you get a two-leg PaymentRequired.","Sign BOTH legs (an accepts[] entry + the extensions[\"platform-fee\"].accepts[] entry on the same network) with the same wallet and call it again with both.","verdict \"ok\" = your client can pay URLGate. Nothing is ever settled."],"production":["Call payment_compat_check on production (https://urlgate.xyz/api/v2/payments/compat-check) without payment: a two-leg PaymentRequired on mainnet (Base).","Sign BOTH legs and call it again with both signatures. Verify-only: no funds move (the wallet only needs to hold the 0.001 USDC test amount for verification).","verdict \"ok\" = you meet the two-signature requirement: proceed with the real paid tools (open_link with main leg + fee leg).","Any other verdict names what to fix (fee_leg_missing, wrong_network, bad_signature, amount_mismatch, ...); fix it and re-run the check before paying."]}}},"servers":[{"url":"https://urlgate.xyz"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Token from POST /api/v2/auth/verify (SIWE)"},"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"x402 SIWX (CAIP-122) proof"},"agentKey":{"type":"http","scheme":"bearer","bearerFormat":"ugk_<id>_<secret>","description":"Agent key created by a signed-in human (dashboard → Settings → Agent keys, or POST /api/v2/me/agent-keys). Only creates links (POST /api/urlgate/agent/create); links belong to the key owner. Also accepted as X-URLGate-Agent-Key."}},"schemas":{"FeeBreakdown":{"type":"object","description":"Per paid open: what the buyer pays, the platform fee (live service_fee_percent, now 0.3%) and what the creator receives. USDC amounts are 6-decimal strings.","required":["appliesTo","buyerPays","serviceFee","serviceFeePercentage","creatorReceives","creatorPercentage"],"properties":{"appliesTo":{"type":"string","const":"each paid open","description":"The split applies to every paid open, not to link creation"},"buyerPays":{"type":"string","description":"USDC the buyer pays per open (= the link price), e.g. \"0.050000\""},"serviceFee":{"type":"string","description":"USDC platform fee per open, e.g. \"0.000150\""},"serviceFeePercentage":{"type":"number","description":"Platform fee in percent, e.g. 0.3"},"creatorReceives":{"type":"string","description":"USDC the creator receives per open, e.g. \"0.049850\""},"creatorPercentage":{"type":"number","description":"Creator share in percent (100 - serviceFeePercentage), e.g. 99.7"}}},"FreeQuota":{"type":"object","description":"Free links for this wallet today (UTC). In a 402 it says why the fee applies.","properties":{"tier":{"type":"string","enum":["free","premium"]},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resetsAt":{"type":"string","format":"date-time"},"agentKey":{"type":"object","description":"The agent key cap: { dailyCap, used, remaining }"}}},"NextStep":{"type":"object","required":["action","description"],"properties":{"action":{"type":"string","enum":["sign_in","use_agent_key","pay_0.01","upgrade","wait","create_link","compat_check"]},"description":{"type":"string"},"how":{"type":"string"},"url":{"type":"string"},"amount":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}},"LimitError":{"type":"object","description":"Quota / limit errors (402 fee fallback, 429 rate_limited, 401 agent key problems)","properties":{"code":{"type":"string","enum":["anonymous","free_quota_exhausted","new_wallet_quota_exhausted","agent_key_cap_reached","free_global_ceiling","free_creation_paused","paid_only","rate_limited","invalid_agent_key","agent_key_revoked","agent_key_expired"]},"message":{"type":"string"},"freeQuota":{"$ref":"#/components/schemas/FreeQuota"},"nextSteps":{"type":"array","items":{"$ref":"#/components/schemas/NextStep"}},"retryAfterSeconds":{"type":"integer"}}},"CreatedLink":{"type":"object","required":["success","shortcode","shortUrl","destinationUrl","price","creatorWallet","feeBreakdown","createdAt"],"properties":{"success":{"type":"boolean"},"shortcode":{"type":"string"},"shortUrl":{"type":"string","format":"uri"},"destinationUrl":{"type":"string","format":"uri"},"price":{"type":"string","description":"USDC per open, 6 decimals"},"creatorWallet":{"type":"string"},"feeBreakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"createdAt":{"type":"string","format":"date-time"},"title":{"type":"string"},"description":{"type":"string"},"afterPay":{"type":"string","enum":["receipt","redirect"]},"networks":{"type":"array","items":{"type":"string"}},"agentCreated":{"type":"boolean","description":"Only on /api/urlgate/agent/create"},"creationMode":{"type":"string","enum":["free_quota","paid","free_config"],"description":"API / MCP creation: free within the daily quota, or paid via x402"},"agentKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"description":"When created with an agent key"},"freeQuota":{"$ref":"#/components/schemas/FreeQuota"}}}}},"paths":{"/{code}":{"get":{"operationId":"openLink","summary":"Open a paid short link","description":"Each short link is its own x402 resource: GET /<code> answers 402 with a PAYMENT-REQUIRED header carrying that link's price (at least 0.01 USDC) and creator payTo, plus the platform-fee leg. An unknown code returns 404. Sign-in is optional (Bearer / SIGN-IN-WITH-X).","security":[],"responses":{"200":{"description":"Paid: { success, destination }"},"302":{"description":"Paid (browser): redirect to destination"},"402":{"description":"Payment required. See PAYMENT-REQUIRED header (x402 v2)."}},"tags":["Open (pay for) a link"],"x-mcp-tool":"open_link"}},"/api/urlgate/{code}/info":{"get":{"operationId":"linkInfo","security":[],"summary":"Link metadata (never the destination)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metadata"}},"tags":["Link metadata"],"x-mcp-tool":"get_link_info"}},"/api/urlgate/agent/create":{"post":{"operationId":"createLink","summary":"Create a paid short link (agents, API, MCP, scripts). Signed in (Bearer / SIGN-IN-WITH-X) or with an agent key: FREE within the daily quota (10/day, 100 with Premium, 3/day for new wallets). Anonymous, over quota or free creation paused: creation fee 0.01 USDC via x402 (the 402 body says why: code, freeQuota, nextSteps). The website's create form is always free.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}],"x402Version":2,"currency":"USDC","networks":["eip155:8453","eip155:137","eip155:42161"]},"security":[{},{"bearer":[]},{"siwx":[]},{"agentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","price"],"properties":{"url":{"type":"string","format":"uri","description":"Destination (http / https) revealed after payment"},"price":{"type":"string","description":"USDC, e.g. \"0.05\". Minimum 0.01, max 6 decimals"},"wallet":{"type":"string","description":"Payout wallet (receives 99.7% of opens (0.3% platform fee)). Optional: defaults to the signed-in wallet (or the agent key owner), else the wallet paying the creation fee; any other address is refused (403)"},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,20}$"},"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":500},"afterPay":{"type":"string","enum":["receipt","redirect"]},"networks":{"type":"array","items":{"type":"string"},"minItems":1,"description":"CAIP-2 ids to sell on: at least one, all from GET /api/v2/networks. Omit for every enabled network. [] → 400 networks_required; a disabled or unknown id → 400 network_unavailable"}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedLink"}}}},"401":{"description":"Agent key invalid / revoked / expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitError"}}}},"402":{"description":"Creation fee required (anonymous, over quota, paused, paid-only): PAYMENT-REQUIRED header; body code + freeQuota + nextSteps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitError"}}}},"403":{"description":"wallet_banned | domain_blocked | Creator Mismatch | premium_required"},"409":{"description":"Shortcode taken / payment reused / duplicate_link (existing link returned)"},"429":{"description":"rate_limited (per wallet, agent key or IP; Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitError"}}}}},"tags":["Create a link"],"x-mcp-tool":"create_link"}},"/api/v2/auth/nonce":{"get":{"operationId":"authNonce","security":[],"summary":"Get SIWE nonce (+ message if ?address=)","responses":{"200":{"description":"Nonce"}},"tags":["Sign in with Ethereum"],"x-mcp-tool":"sign_in"}},"/api/v2/auth/verify":{"post":{"operationId":"authVerify","security":[],"summary":"Exchange signed SIWE message for a session token (agents: 24h, humans: 7d)","responses":{"200":{"description":"Token"},"401":{"description":"Bad signature"}},"tags":["Sign in with Ethereum"],"x-mcp-tool":"sign_in"}},"/api/v2/auth/revoke":{"post":{"operationId":"authRevoke","summary":"Revoke the presented token (scope \"current\"), all tokens for the wallet (\"all\"), or one by jti","security":[{"bearer":[]},{"siwx":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["current","all"]},"jti":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked"},"401":{"description":"No valid credentials"}},"tags":["Sessions"],"x-mcp-tool":"sessions"}},"/api/v2/auth/logout":{"post":{"operationId":"authLogout","security":[],"summary":"Revoke the presented token and clear the session cookie","responses":{"200":{"description":"Signed out"}},"tags":["Sessions"],"x-mcp-tool":"sessions"}},"/api/v2/auth/sessions":{"get":{"operationId":"authSessions","summary":"List live sessions/tokens for the signed-in wallet","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"Sessions"}},"tags":["Sessions"],"x-mcp-tool":"sessions"}},"/api/v2/points/rules":{"get":{"operationId":"pointsRules","security":[],"summary":"Points rules and eligibility","responses":{"200":{"description":"Rules"}},"tags":["Points rules"],"x-mcp-tool":"points_rules"}},"/api/v2/me/links":{"get":{"operationId":"myLinks","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"Your links"}},"tags":["My links"],"x-mcp-tool":"my_links"}},"/api/v2/points/me":{"get":{"operationId":"myPoints","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"Points"}},"tags":["My points"],"x-mcp-tool":"my_points"}},"/api/v2/points/leaderboard":{"get":{"operationId":"leaderboard","security":[],"summary":"Public top-100 leaderboard ranked by confirmed points only (ties: earliest earner). pending = points in an open review (pending or held; not voided, confirmed or expired), never ranked. Banned wallets excluded. Wallets shortened. Cache-Control: public, max-age=60","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Alternative to offset: offset = (page - 1) * limit"}],"responses":{"200":{"description":"{ leaderboard: [{ rank, wallet (0x1234…abcd), final, points, pending, events, kind? }], limit, offset, page, total, hasMore, rules }"}},"tags":["Leaderboard"],"x-mcp-tool":"points_leaderboard"}},"/api/v2/points/leaderboard/me":{"get":{"operationId":"leaderboardMe","summary":"My rank: { rank | null, finalized, pending, onBoard, reason }","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"My rank"},"401":{"description":"Sign in first"}},"tags":["My leaderboard rank"],"x-mcp-tool":"points_leaderboard_me"}},"/api/v2/links/{code}/status":{"get":{"operationId":"linkStatus","summary":"Whether a link can be bought, and why not (paused, sold out, expired, removed by seller, removed by URLGate + reason code)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"OK"}},"tags":["Availability / takedown status"],"x-mcp-tool":"link_status"}},"/api/v2/links/{code}/report":{"post":{"operationId":"reportLink1","summary":"Report a link for moderation (no sign-in needed; one report per reporter per link)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{},{"bearer":[]},{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["scam_phishing","malware","illegal","dmca","spam","child_sexual_exploitation","other"],"description":"scam_phishing | malware | illegal | dmca | spam | child_sexual_exploitation | other (older values phishing_malware, legal, tos_violation are still accepted). child_sexual_exploitation takes the link offline at once pending review, preserves the records and queues a report to NCMEC"},"details":{"type":"string","maxLength":2000},"email":{"type":"string","format":"email","description":"Optional, for follow-up. Deleted after 30 days."},"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Optional contact wallet (unverified). Deleted after 30 days."},"formToken":{"type":"string","description":"Browsers only (requests with an Origin header): token from GET /api/v2/reports/form-token, at least 3 s old"}}}}}},"responses":{"202":{"description":"Accepted: { success, reportId, message }"},"400":{"description":"Invalid reason / field / link, or a rejected browser form (code form_too_fast, form_token_invalid, form_expired, form_rejected)"},"403":{"description":"Browser request from another site (code cross_origin)"},"404":{"description":"Short link not found"},"409":{"description":"Already reported by you (code already_reported, reportId) or already removed by URLGate (code link_removed)"},"429":{"description":"Too many requests from this IP (10 reports per minute)"}},"tags":["Report a link"],"x-mcp-tool":"report_link"}},"/api/v2/reports":{"post":{"operationId":"reportLink2","summary":"Report a link given its short code or full URL (the /report.html form)","security":[{},{"bearer":[]},{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["link","reason"],"properties":{"link":{"type":"string","description":"Short code or full URLGate URL, e.g. https://urlgate.xyz/abc123"},"reason":{"type":"string","enum":["scam_phishing","malware","illegal","dmca","spam","child_sexual_exploitation","other"],"description":"scam_phishing | malware | illegal | dmca | spam | child_sexual_exploitation | other (older values phishing_malware, legal, tos_violation are still accepted). child_sexual_exploitation takes the link offline at once pending review, preserves the records and queues a report to NCMEC"},"details":{"type":"string","maxLength":2000},"email":{"type":"string","format":"email","description":"Optional, for follow-up. Deleted after 30 days."},"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Optional contact wallet (unverified). Deleted after 30 days."},"formToken":{"type":"string","description":"Browsers only (requests with an Origin header): token from GET /api/v2/reports/form-token, at least 3 s old"}}}}}},"responses":{"202":{"description":"Accepted: { success, reportId, message }"},"400":{"description":"Invalid reason / field / link, or a rejected browser form (code form_too_fast, form_token_invalid, form_expired, form_rejected)"},"403":{"description":"Browser request from another site (code cross_origin)"},"404":{"description":"Short link not found"},"409":{"description":"Already reported by you (code already_reported, reportId) or already removed by URLGate (code link_removed)"},"429":{"description":"Too many requests from this IP (10 reports per minute)"}},"tags":["Report a link"],"x-mcp-tool":"report_link"}},"/api/v2/me/unlocks":{"get":{"operationId":"myUnlocks","summary":"Links I paid for (also taken-down ones, marked unavailable); ?format=csv","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["My unlocks"],"x-mcp-tool":"my_unlocks"}},"/api/v2/receipts/{id}":{"get":{"operationId":"receipt","summary":"A payment receipt (link access or membership)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"OK"}},"tags":["Receipt"],"x-mcp-tool":"get_receipt"}},"/api/v2/payments/compat-check":{"post":{"operationId":"paymentCompatCheck1","summary":"FREE, verify-only rehearsal of the two-leg x402 payment (main leg + platform-fee leg) on this deployment's networks (testnet on preview, mainnet on production). First call: 402 + PAYMENT-REQUIRED (tiny amounts, 30 s validBefore). Retry with PAYMENT-SIGNATURE + PAYMENT-SIGNATURE-FEE: both legs are verified by the URLGate settler (signature, balance, simulation), NEVER settled; answers a verdict. The preview testnet test link REQUIRES a wallet with Base Sepolia testnet + test USDC. If your wallet can't use testnet, follow the production path: run payment_compat_check on production (verify-only, no funds move) and, if you meet the two-signature requirements, proceed with the real paid tools. Testnet path: 1. wallet on Base Sepolia with test USDC; 2. payment_compat_check on the preview deployment; 3. sign both legs, call again; 4. verdict ok = ready. Production path: 1. payment_compat_check on production (verify-only, no funds move); 2. sign both legs, call again; 3. verdict ok = proceed with the real paid tools.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"description":"No fields needed (an empty object or no body). Send the signed legs as headers: PAYMENT-SIGNATURE (main) + PAYMENT-SIGNATURE-FEE (platform fee)."}}}},"responses":{"200":{"description":"{ compatCheck: true, verifyOnly: true, settled: false, verdict, ok, message, network, payer, twoLeg, legs: { main, fee }, nextSteps, mode, guide }","content":{"application/json":{"schema":{"type":"object","required":["compatCheck","verifyOnly","settled","verdict","ok"],"properties":{"compatCheck":{"type":"boolean","const":true},"verifyOnly":{"type":"boolean","const":true},"settled":{"type":"boolean","const":false},"verdict":{"type":"string","enum":["ok","fee_leg_missing","main_leg_missing","wrong_network","bad_signature","amount_mismatch","requirement_mismatch","payer_mismatch","expired","insufficient_funds","facilitator_unavailable"]},"ok":{"type":"boolean"},"message":{"type":"string"},"network":{"type":["string","null"]},"payer":{"type":["string","null"]},"twoLeg":{"type":"boolean"},"legs":{"type":"object","properties":{"main":{"type":"object","properties":{"present":{"type":"boolean"},"ok":{"type":"boolean"},"verdict":{"type":["string","null"]},"detail":{"type":["string","null"]},"required":{"type":"boolean"}}},"fee":{"type":"object","properties":{"present":{"type":"boolean"},"ok":{"type":"boolean"},"verdict":{"type":["string","null"]},"detail":{"type":["string","null"]},"required":{"type":"boolean"}}}}},"nextSteps":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["mainnet","testnet","any"]},"guide":{"type":"object"}}}}}},"402":{"description":"First call (no signatures): two-leg PaymentRequired in the PAYMENT-REQUIRED header and the body (+ guide with both paths)"},"429":{"description":"Rate limited (a few calls a minute per IP)"}},"tags":["Payment compatibility check (free, verify-only)"],"x-mcp-tool":"payment_compat_check"},"get":{"operationId":"paymentCompatCheck2","summary":"FREE, verify-only rehearsal of the two-leg x402 payment (main leg + platform-fee leg) on this deployment's networks (testnet on preview, mainnet on production). First call: 402 + PAYMENT-REQUIRED (tiny amounts, 30 s validBefore). Retry with PAYMENT-SIGNATURE + PAYMENT-SIGNATURE-FEE: both legs are verified by the URLGate settler (signature, balance, simulation), NEVER settled; answers a verdict. The preview testnet test link REQUIRES a wallet with Base Sepolia testnet + test USDC. If your wallet can't use testnet, follow the production path: run payment_compat_check on production (verify-only, no funds move) and, if you meet the two-signature requirements, proceed with the real paid tools. Testnet path: 1. wallet on Base Sepolia with test USDC; 2. payment_compat_check on the preview deployment; 3. sign both legs, call again; 4. verdict ok = ready. Production path: 1. payment_compat_check on production (verify-only, no funds move); 2. sign both legs, call again; 3. verdict ok = proceed with the real paid tools.","security":[],"responses":{"200":{"description":"{ compatCheck: true, verifyOnly: true, settled: false, verdict, ok, message, network, payer, twoLeg, legs: { main, fee }, nextSteps, mode, guide }","content":{"application/json":{"schema":{"type":"object","required":["compatCheck","verifyOnly","settled","verdict","ok"],"properties":{"compatCheck":{"type":"boolean","const":true},"verifyOnly":{"type":"boolean","const":true},"settled":{"type":"boolean","const":false},"verdict":{"type":"string","enum":["ok","fee_leg_missing","main_leg_missing","wrong_network","bad_signature","amount_mismatch","requirement_mismatch","payer_mismatch","expired","insufficient_funds","facilitator_unavailable"]},"ok":{"type":"boolean"},"message":{"type":"string"},"network":{"type":["string","null"]},"payer":{"type":["string","null"]},"twoLeg":{"type":"boolean"},"legs":{"type":"object","properties":{"main":{"type":"object","properties":{"present":{"type":"boolean"},"ok":{"type":"boolean"},"verdict":{"type":["string","null"]},"detail":{"type":["string","null"]},"required":{"type":"boolean"}}},"fee":{"type":"object","properties":{"present":{"type":"boolean"},"ok":{"type":"boolean"},"verdict":{"type":["string","null"]},"detail":{"type":["string","null"]},"required":{"type":"boolean"}}}}},"nextSteps":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["mainnet","testnet","any"]},"guide":{"type":"object"}}}}}},"402":{"description":"First call (no signatures): two-leg PaymentRequired in the PAYMENT-REQUIRED header and the body (+ guide with both paths)"},"429":{"description":"Rate limited (a few calls a minute per IP)"}},"tags":["Payment compatibility check (free, verify-only)"],"x-mcp-tool":"payment_compat_check"}},"/api/urlgate/create":{"post":{"operationId":"createLink1","summary":"Create a link. The website's create form (cookie session + X-URLGate-Form + X-CSRF-Token): free. API, MCP and scripts follow /api/urlgate/agent/create: free within the daily quota with Bearer / SIGN-IN-WITH-X / an agent key, else the 0.01 USDC agent fee via x402 (a cookie session alone is not an API credential)","security":[{},{"bearer":[]},{"siwx":[]},{"agentKey":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}],"x402Version":2,"currency":"USDC","networks":["eip155:8453","eip155:137","eip155:42161"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","price"],"properties":{"url":{"type":"string","format":"uri","description":"Destination (http / https) revealed after payment"},"price":{"type":"string","description":"USDC, e.g. \"0.05\". Minimum 0.01, max 6 decimals"},"wallet":{"type":"string","description":"Payout wallet (receives 99.7% of opens (0.3% platform fee)). Optional: defaults to the signed-in wallet (or the agent key owner), else the wallet paying the creation fee; any other address is refused (403)"},"shortcode":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,20}$"},"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":500},"afterPay":{"type":"string","enum":["receipt","redirect"]},"networks":{"type":"array","items":{"type":"string"},"minItems":1,"description":"CAIP-2 ids to sell on: at least one, all from GET /api/v2/networks. Omit for every enabled network. [] → 400 networks_required; a disabled or unknown id → 400 network_unavailable"}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedLink"}}}},"402":{"description":"Creation fee required (0.01 USDC): anonymous or over the free quota (not the website's create form). Decided before the body is validated, so a body-less probe gets the challenge: PAYMENT-REQUIRED header (x402 v2, with extensions.bazaar), body code + freeQuota + nextSteps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitError"}}}}},"tags":["Create a link"],"x-mcp-tool":"create_link"}},"/api/v2/agents/get-started":{"get":{"operationId":"getStarted","summary":"FREE. How to create links as an agent: the three paths (own wallet = free daily quota; no wallet = agent key from a human; anonymous / over quota = 0.01 USDC via x402), live quotas and limits, and, with credentials (Bearer, SIGN-IN-WITH-X or an agent key), your tier, quota used / remaining, reset time and machine-readable nextSteps","security":[{},{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"{ pricing, you: { signedIn, via, wallet, tier, quota: { limit, used, remaining, resetsAt } }, nextSteps, paths, premium, compatCheck, links }"}},"tags":["Get started: pricing, my quota, next steps"],"x-mcp-tool":"get_started"}},"/api/v2/pricing":{"get":{"operationId":"pricingAndLimits","summary":"FREE. Same document as /api/v2/agents/get-started (alias): creation pricing, free daily quotas, agent-key limits, rate limits, Premium perks, and your own quota when you send credentials","security":[{},{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"}},"tags":["Pricing and limits"],"x-mcp-tool":"pricing_and_limits"}},"/api/v2/links/{code}":{"get":{"operationId":"myLink","summary":"Owner view of a link (destination, options, entitlements)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["One of my links"],"x-mcp-tool":"get_my_link"},"patch":{"operationId":"updateLink","summary":"Edit price, title, description, after-pay, chains (at least one enabled network; null = all); premium: receipt message, expiry, max uses, timed passes, destination after first sale","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Edit link options"],"x-mcp-tool":"update_link"}},"/api/v2/links/{code}/pause":{"post":{"operationId":"setLinkStatus1","summary":"Pause my link","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Pause / resume / remove / restore"],"x-mcp-tool":"set_link_status"}},"/api/v2/links/{code}/resume":{"post":{"operationId":"setLinkStatus2","summary":"Resume my link","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Pause / resume / remove / restore"],"x-mcp-tool":"set_link_status"}},"/api/v2/links/{code}/remove":{"post":{"operationId":"setLinkStatus3","summary":"Remove my link","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Pause / resume / remove / restore"],"x-mcp-tool":"set_link_status"}},"/api/v2/links/{code}/restore":{"post":{"operationId":"setLinkStatus4","summary":"Restore my link","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Pause / resume / remove / restore"],"x-mcp-tool":"set_link_status"}},"/api/v2/links/{code}/analytics":{"get":{"operationId":"linkAnalytics","summary":"Views, sales, conversion, earnings series, agent vs human split (payerKinds); 90d/all + breakdowns are premium","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Per-link analytics"],"x-mcp-tool":"link_analytics"}},"/api/v2/me/analytics":{"get":{"operationId":"myAnalytics","summary":"Totals and daily earnings across my links","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Earnings overview"],"x-mcp-tool":"my_analytics"}},"/api/v2/links/{code}/payments":{"get":{"operationId":"linkPayments","summary":"Payments for one of my links, each tagged payerKind agent|human|unknown; ?payerKind= filters; ?format=csv (premium)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Sales of a link"],"x-mcp-tool":"link_payments"}},"/api/v2/links/{code}/audit":{"get":{"operationId":"linkAudit","summary":"Audit trail of one of my links (IPs truncated); ?format=csv (premium)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Audit log of my link"],"x-mcp-tool":"link_audit"}},"/api/v2/links/{code}/grants":{"get":{"operationId":"linkGrants1","summary":"List allowlisted wallets and promo codes (stays readable after Premium ends, so grants can still be revoked)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Allowlist, free passes, promo codes"],"x-mcp-tool":"link_grants"},"post":{"operationId":"linkGrants2","summary":"Add an allowlisted wallet or a promo code (premium)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Allowlist, free passes, promo codes"],"x-mcp-tool":"link_grants"}},"/api/v2/links/{code}/grants/{id}":{"delete":{"operationId":"linkGrants3","summary":"Revoke a grant (always allowed)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"},"403":{"description":"Not your link, or a premium-only option (code premium_required)"}},"tags":["Allowlist, free passes, promo codes"],"x-mcp-tool":"link_grants"}},"/api/v2/links/{code}/qr.svg":{"get":{"operationId":"linkQr","summary":"QR code (SVG) for a link","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"OK"}},"tags":["QR code"],"x-mcp-tool":"link_qr"}},"/api/v2/membership":{"get":{"operationId":"membership","summary":"Plan, price (placeholder until set), my tier, period end, renewal reminder, feature list","security":[{},{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"}},"tags":["Membership status"],"x-mcp-tool":"membership_status"}},"/api/v2/membership/purchase":{"post":{"operationId":"membershipPurchase","summary":"Buy 30 days of Premium (5.00 USDC) with USDC via x402 (no auto-renew; stacks)","security":[{},{"bearer":[]},{"siwx":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"5.00"},"protocols":[{"x402":{}}],"x402Version":2,"currency":"USDC","networks":["eip155:8453","eip155:137","eip155:42161"]},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"description":"No fields needed (an empty object or no body). Pay with the PAYMENT-SIGNATURE header. Premium is credited to the signed-in wallet (Bearer / SIGN-IN-WITH-X), else to the paying wallet."}}}},"responses":{"200":{"description":"Paid: Premium credited (PAYMENT-RESPONSE header carries the settlement)","content":{"application/json":{"schema":{"type":"object","required":["success","wallet","membership","network","amount","receipt"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"wallet":{"type":"string","description":"Wallet the Premium period was credited to"},"membership":{"type":"object","properties":{"tier":{"type":"string","enum":["free","premium"]},"state":{"type":"string","enum":["active","renewal_due","expired","revoked","none"]},"active":{"type":"boolean"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"daysLeft":{"type":"integer"},"renewalDue":{"type":"boolean"},"reminderDismissed":{"type":"boolean"},"source":{"type":["string","null"]}}},"transaction":{"type":["string","null"],"description":"Settlement transaction hash"},"network":{"type":"string","description":"CAIP-2 id the payment settled on"},"amount":{"type":"string","description":"USDC paid"},"receipt":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Payment required: PAYMENT-REQUIRED header (x402 v2, one signature) and the same PaymentRequired in the body, plus membership { price, periodDays }"},"403":{"description":"wallet_banned, or not available (sanctions screening)"},"409":{"description":"Payment already used"}},"tags":["Buy / renew Premium"],"x-mcp-tool":"buy_membership"}},"/api/v2/membership/redeem":{"post":{"operationId":"membershipRedeem","summary":"Redeem a premium code: adds its cycles (30 days each) on top of any current period; once per wallet per code","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Redeem a premium code"],"x-mcp-tool":"redeem_premium_code"}},"/api/v2/membership/reminder/dismiss":{"post":{"operationId":"membershipReminder","summary":"Dismiss the renewal reminder for the current period","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Dismiss renewal reminder"],"x-mcp-tool":"dismiss_renewal_reminder"}},"/api/v2/points/prefs":{"post":{"operationId":"pointsPrefs","summary":"Hide or show my wallet on the public leaderboard","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Leaderboard opt-out"],"x-mcp-tool":"set_points_prefs"}},"/api/v2/config":{"get":{"operationId":"siteConfig","summary":"FREE, public. Every fee, price, quota, period and limit in force right now (agent creation fee, platform fee %, minimum link price, free daily quotas, agent-key limits, rate limits, Premium price / period / perks, points pending days, payment networks). Every page and doc is rendered from the same values. Cached 60 s.","security":[],"responses":{"200":{"description":"OK"}},"tags":["Live fees, prices and limits"],"x-mcp-tool":"site_config"}},"/api/v2/events/verify":{"get":{"operationId":"ledger","summary":"Re-walk the hash-chained points ledger","security":[],"responses":{"200":{"description":"OK"}},"tags":["Ledger integrity"],"x-mcp-tool":"verify_ledger"}},"/api/v2/auth/me":{"get":{"operationId":"whoami","summary":"Signed-in wallet, tier, membership","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Who am I"],"x-mcp-tool":"whoami"}},"/api/v2/me/agent-keys":{"get":{"operationId":"agentKeys1","summary":"My agent keys (never the secret), limits for my tier, my free quota today","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Agent keys (settings)"],"x-mcp-tool":"agent_keys"},"post":{"operationId":"agentKeys2","summary":"Create an agent key for a bot without a wallet: { name, dailyCap?, expiresInDays? (1-365, default 90), networks?, scopes? [\"create_links\"] }. The secret (ugk_…) is in this response ONLY. Links made with it belong to my wallet","security":[{"bearer":[]},{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":60},"dailyCap":{"type":"integer","minimum":1,"description":"Free links per UTC day through this key (max depends on tier)"},"expiresInDays":{"type":"integer","minimum":1,"maximum":365},"networks":{"type":"array","items":{"type":"string"},"minItems":1,"description":"CAIP-2 ids links made with the key may sell on; omit for all enabled"},"scopes":{"type":"array","items":{"type":"string","enum":["create_links"]}}}}}}},"responses":{"201":{"description":"{ key (shown once), agentKey, message }"},"400":{"description":"invalid_name | invalid_daily_cap | daily_cap_too_high | invalid_expiry | invalid_scopes | network_unavailable"},"401":{"description":"Sign in first"},"409":{"description":"key_limit_reached (nextSteps: upgrade)"}},"tags":["Agent keys (settings)"],"x-mcp-tool":"agent_keys"}},"/api/v2/me/agent-keys/{id}":{"delete":{"operationId":"agentKeys3","summary":"Revoke one of my agent keys (immediately)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Agent keys (settings)"],"x-mcp-tool":"agent_keys"}},"/api/v2/me/preferences":{"get":{"operationId":"preferences1","summary":"My saved display preferences: { wallet, preferences: { theme }, updatedAt, allowed, defaults }. theme is null until chosen","security":[{"bearer":[]},{"siwx":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Sign in first"}},"tags":["Colour scheme (settings)"],"x-mcp-tool":"my_preferences"},"patch":{"operationId":"preferences2","summary":"Save my colour scheme (own wallet only): { \"theme\": \"green\" | \"blue\" | \"system\" } or null to reset. Unknown fields or values: 400","security":[{"bearer":[]},{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["theme"],"additionalProperties":false,"properties":{"theme":{"type":["string","null"],"enum":["green","blue","system",null],"description":"blue (default, URLGate brand blue) | green (the original green look) | system (follow the device, blue palette); null forgets the saved choice"}}}}}},"responses":{"200":{"description":"{ wallet, preferences: { theme }, updatedAt, allowed: { theme }, defaults: { theme } }"},"400":{"description":"invalid_body | unknown_field | invalid_theme"},"401":{"description":"Sign in first"},"403":{"description":"Cross-origin cookie request (bad_origin) or suspended wallet (wallet_banned)"},"429":{"description":"Too many requests"}},"tags":["Colour scheme (settings)"],"x-mcp-tool":"my_preferences"}},"/api/v2/networks":{"get":{"operationId":"networks","summary":"Enabled payment networks (CAIP-2) and their USDC; mode mainnet|testnet; default first","security":[],"responses":{"200":{"description":"OK"}},"tags":["Payment networks"],"x-mcp-tool":"list_networks"}},"/api/v2/reports/form-token":{"get":{"operationId":"reportFormToken","security":[],"summary":"Anti-bot token for the /report.html form (same-origin only, no CORS). Browser report submissions must carry it, at least 3 s after issue; API and MCP callers do not need it","responses":{"200":{"description":"{ token, minFillMs, expiresInMs }"}}}},"/mcp":{"post":{"operationId":"mcp","security":[],"summary":"MCP (Streamable HTTP, JSON-RPC). Tools: open_link, get_link_info, link_status, report_link, my_unlocks, get_receipt, payment_compat_check, create_link, get_started, pricing_and_limits, my_links, get_my_link, update_link, set_link_status, link_analytics, my_analytics, link_payments, link_audit, link_grants, link_qr, membership_status, buy_membership, redeem_premium_code, dismiss_renewal_reminder, my_points, set_points_prefs, points_leaderboard, points_leaderboard_me, points_rules, site_config, verify_ledger, sign_in, whoami, sessions, agent_keys, my_preferences, list_networks, open_link_instructions","responses":{"200":{"description":"JSON-RPC response"}}}}}}