Client setup

claude mcp add \
  --transport http valuly \
  https://valuly.ai/api/mcp \
  --header "Authorization: Bearer val_live_..."

{
  "mcpServers": {
    "valuly": {
      "url": "https://valuly.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer val_live_..."
      }
    }
  }
}

curl https://valuly.ai/api/mcp/tools

Values a domain against 94,567 recorded market sales. Returns a market band (25th–75th percentile of real sales for names of the same class and length), the extension’s wholesale channel alongside it, and an exact-match screen of the US federal trademark register. Every response restates the model's measured error, so a caller reading only the midpoint still carries its uncertainty. The wholesale figure is one average per extension and carries its own scope note saying so — it is never a price for the name you asked about.

Lists the key holder's domains with last recorded valuation, acquisition cost, tags and renewal date. No arguments. Rows carry no grade and no score — both were withdrawn, because the composite behind them measured a rank correlation of +0.045 against held-out price with a median error straddling zero, and an agent reads a letter grade as a verdict.

Returns recorded valuation snapshots for one domain, oldest first. Snapshots come from appraisals actually run, so a domain appraised once has one point — the tool says so rather than returning an empty list without explanation.

Computes 12, 24 and 36-month lease-to-own schedules from the valuation midpoint, or from an agreed sale price you supply. Arithmetic only: the 24 and 36-month terms carry 10% and 18% financing fees. Valuly does not broker, escrow or guarantee any transaction.

Lists portfolio domains whose registrar-reported expiry falls inside a window you choose. Dates are a snapshot from your last registrar import, not a live feed — credentials are never stored, so nothing refreshes them in the background. Every response reports how many domains actually have expiry data, because “nothing is expiring” and “we have no data” are different answers.

Whether the same name is registered under other extensions, from a live lookup against each registry’s own RDAP service with DNS delegation as a second check. Every result is one of three values, and the third one is the point: registered, unregistered, or unverified — which means we could not find out, and never means available. A timeout or registry error returns unverified too. Of the six extensions checked by default, only .co has no reachable RDAP service — this page used to name .io and .me as well, which stopped being true when Identity Digital's endpoint was added: both are confirmable, and the stale claim understated the product by saying a lookup could not answer when it could. Nothing collapses into “available”.

Two limits travel in every response. unregistered is not purchasable — premium, reserved and pending-delete names all read as unregistered without being available at the standard fee, and no price is checked. And “responds on https” is not “developed”, because a parked or for-sale page responds too. Rate limited separately at 60 calls per hour: each call queries domain registries directly, and their terms prohibit high-volume automated querying.

Names from a one-sentence description of what you’re building, ranked by our sayability model and the market band for each name’s shape. A language model proposes some of the candidates; it never scores or ranks them. No name in the result is confirmed purchasable, and no field reports that it is.

Registration per extension is one of four values: taken, unregistered, marketed — registered and listed for sale, so buyable but never at the registration fee — or unverified, which means we could not find out and never means available. unregistered is a registry reading at a moment in time, not purchasability: premium, reserved, registry-held and pending-delete names all read that way, and this tool checks no price. The four definitions ship inside every response, next to the statuses they describe, because a tool description is read once at connection time while the result is what a model actually reasons over.

Names are screened for exact matches against the live US federal trademark register. A hit is reported with its owner; a miss reports nothing — there is deliberately no clear or conflicts: false field, because absence of an exact match in one register is absence of evidence and a boolean there is exactly what would be read as clearance. Rate limited at 20 calls per hour for the language-model spend, and each call also draws on the same 60/hour registry budget as check_sibling_tlds, since one call fans out across candidates and extensions.

On find_buyer_prospects

This tool was previously listed and is still not exposed — but the reason has changed, and half of it now ships. Its only implementation returned a fixed table asserting which TLD variants were “taken and developed”, identically for every domain, without checking anything. That part is fixed: registration status is a real registry lookup, and it is available above as check_sibling_tlds, named for what it returns rather than for what you might do with the answer.

What is still missing is the other half. The buyer categories behind it are the same three strings for every domain, so a tool by that name would imply it had identified specific prospects for your name when it had not — the same over-claim, moved from the data to the label. It ships when the category signal is real and per-domain.

Body: { "domain": "example.com", "askingPrice": 5000 } — askingPrice optional. Returns the market band, the readability percentile and the trademark screen. There is no grade and no score — the composite behind them measured a rank correlation of +0.045 against held-out price and was withdrawn. See the response schema below.

{
  "success": true,
  "report": { /* see the table below */ },
  "basis": "Heuristic model centred on NameBio market statistics…",
  "trademark": {
    "checked": true,
    "matches": [ { "mark": "STRIPE", "owner": "…", "status": "LIVE", "class": "…" } ]
  },
  "usage": { "used": 12, "limit": 100, "remaining": 88, "resetsAt": "2026-09-01T00:00:00Z" }
}

Body: { "domains": ["a.com", "b.io"] }. 100 domains per request on Business, 25 on Pro. Bulk is a paid feature: Free returns 402 UPGRADE_REQUIRED, and an over-sized batch returns 400 BATCH_TOO_LARGE with the limit rather than silently truncating. Each domain gets a full valuation with its own trademark screen, not a bulk-rate approximation.

{
  "success": true,
  "requested": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "domain": "a.com", "success": true,  "report": { /* same shape as /single */ } },
    { "domain": "b.io",  "success": true,  "report": { /* … */ } },
    { "domain": "not a domain", "success": false, "error": "Not a valid domain name." }
  ],
  "usage": { "used": 12, "limit": 100, "remaining": 88, "resetsAt": "2026-09-01T00:00:00Z" }
}

Body: { "idea": "fast payments for small shops", "minLength": 4, "maxLength": 9 }. Only idea is required, and it is truncated at 400 characters. It suggests names. It does not tell you a name can be bought, and it runs no clearance search — registration status is a registry answer at one moment, and the trademark check is an exact-match screen of one register.

Every plan can call it — this is not a paid feature. 20 requests per hour per account, and it does not draw on your monthly appraisal allowance; a suggestion is not an appraisal. Your plan sets how many of the returned names get their registration checked, not whether you can call it. There is no limit parameter on this endpoint; the MCP tool has one, the REST endpoint returns up to 24.

{
  "success": true,          /* the HTTP envelope */
  "ok": true,               /* the generator. ABSENT on a failure, not false */
  "idea": "fast payments for small shops",
  "seeds": ["fast", "payments", "shops"],
  "seedPlacements": [ { "word": "fast", "placement": { "start": 157, "end": 78, "middle": 6, "lean": "prefix" } } ],
  "modelUsed": false,
  "note": null,
  "tldsChecked": [".com", ".io", ".ai", ".co"],
  "lookupBudget": 24,
  "lookupsUsed": 24,
  "lengthFilter": null,
  "checked": { "availability": true, "trademark": true },
  "availabilityCaveat": "Not registered according to the registry at the time of this check…",
  "disclaimer": "…",
  "suggestions": [
    {
      "label": "fastable", "source": "recombined", "how": "suffix able",
      "sayability": 9.88, "class": "derived", "length": 8, "keepsSeedWord": true,
      "bandP50": 2500, "bandBasis": "class+length",
      "tlds": [ { "tld": ".com", "status": "taken", "source": "rdap", "reason": null } ]
    },
    { "label": "paylane", "how": "compound", "tlds": null, /* … not checked — see below */ }
  ]
}

Body: { "domain": "paylane.com" }. 30 requests per hour per account. This is the only endpoint that returns a real registrar price, and it is deliberately separate from /api/suggest: the registrar answers roughly one request every ten seconds, so it cannot back a list. Keeping it its own endpoint means a suggestion run can never fan out into it.

{
  "success": true,
  "domain": "paylane.com",
  "source": "porkbun",
  "status": "unregistered",
  "premium": false,
  "price": 11.06,
  "renewalPrice": 11.06,
  "currency": "USD",
  "reason": null,
  "checkedAt": "2026-08-04T04:12:00.000Z",
  "caveat": "Registration status and price come from Porkbun at the time of this check…"
}

The MCP server. See §3.

Unauthenticated. Returns the tool list, endpoint and auth scheme.

{
  "success": true,
  "protocol_version": "2024-11-05",
  "server_name": "valuly-domain-valuation",
  "endpoint": "https://valuly.ai/api/mcp",
  "transport": "JSON-RPC 2.0 over HTTP POST",
  "authentication": "Authorization: Bearer <val_live_ API key>",
  "tools": [ { "name": "appraise_domain", "description": "…", "inputSchema": { /* JSON Schema */ } } ]
}

Four served routes that this reference did not name at all — while §7 published their rate limit. They are matched by pattern rather than by exact path, which is why a pathname === '…' inventory of the router missed them. All four accept val_live_ keys. You send the registrar credentials with the request; they are used for that one call and never stored, which is why nothing refreshes expiry dates in the background and why every imported row carries the date it was imported.

POST /api/godaddy/import
{ /* registrar credentials — the fields each one needs are in Settings → Portfolio */ }

200 OK
{
  "success": true,
  "source": "GoDaddy REST API (api.godaddy.com)",
  "domains": [
    { "domain": "EXAMPLE.COM", "tld": "com", "status": "ACTIVE",
      "cost": null, "autoRenew": true, "expires": "2027-03-14" }
  ]
}

Unauthenticated liveness check.

{ "status": "ok", "service": "valuly-edge-api" }

curl -X POST https://valuly.ai/api/appraise/single \
  -H "Authorization: Bearer val_live_EXAMPLE_KEY_NOT_REAL" \
  -H "Content-Type: application/json" \
  -d '{"domain": "workspaces.ai", "askingPrice": 5000}'

const response = await fetch('https://valuly.ai/api/appraise/single', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer val_live_EXAMPLE_KEY_NOT_REAL',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'workspaces.ai', askingPrice: 5000 })
});
const result = await response.json();

import requests
res = requests.post("https://valuly.ai/api/appraise/single",
    headers={"Authorization": "Bearer val_live_EXAMPLE_KEY_NOT_REAL"},
    json={"domain": "workspaces.ai", "askingPrice": 5000})
data = res.json()

curl -X POST https://valuly.ai/api/mcp \
  -H "Authorization: Bearer val_live_EXAMPLE_KEY_NOT_REAL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "appraise_domain",
      "arguments": { "domain": "workspaces.ai" }
    }
  }'

Limits

• Valuations: 60 requests / minute on Free, 300 requests / minute on Pro, 1,200 requests / minute on Business.
• Monthly allowance: 5 appraisals / mo on Free, 100 appraisals / mo on Pro, 500 appraisals / mo on Business.
• MCP requests: 240 per hour. Tool calls that run a valuation also draw on both limits above.
• Registrar imports: 20 per hour, across POST /api/cloudflare/import, /api/godaddy/import, /api/porkbun/import and /api/namecheap/import.
• Name suggestions: 20 per hour on POST /api/suggest — a spend ceiling, because every call bills a language-model request to us. A further 30 per hour on POST /api/suggest/check, which is below what the registrar upstream allows the whole product (one request per ten seconds), so a caller who ignores it spends a budget shared with everyone else and gets unverified for it.
• Registry lookups over MCP: 60 per hour, shared between check_sibling_tlds and suggest_domain_names. Registry RDAP terms prohibit high-volume automated querying, so this is terms compliance rather than politeness.
• Unauthenticated endpoints: GET /api/comps 30 per hour by IP (a bandwidth budget — the payload is the 774 KB comps set, and a repeat visitor arriving with If-None-Match gets a 304 without touching the counter); POST /api/contact 5 per hour by IP; POST /api/telemetry/client-error 30 per hour by IP.

The per-minute figure is a burst ceiling; the monthly allowance is how much you may actually run. They are separate: exceeding the ceiling returns 429, exhausting the allowance returns 402 with code QUOTA_EXCEEDED and the date it resets. API traffic draws on the same allowance as the application — it is not extra capacity. Other endpoints (authentication, registrar import, invitations, key creation) have their own budgets, the same on every plan. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset are returned on a 429, and only there — they tell you how long to wait once you have been refused, not how much budget is left before you are. Do not poll a successful response for them; there is no header to read until you are over.

Status codes

Webhooks

Outbound webhooks are not available. Valuations are computed synchronously and return in the same response, so there is no asynchronous job to notify you about. If you want notification on a schedule, use scheduled re-appraisal in the app.