The Namecheap API is an XML-over-HTTPS surface that lets a developer register, transfer, and manage domains, set DNS records, and check availability — all from a script, a CI job, or a back-office tool. The API is not REST, the API is not JSON, the API is XML with a strict schema and a per-account IP whitelist. The choice is unusual, the choice is on purpose, and the choice is the first thing the developer has to understand before the first call returns a useful response.
The reason “namecheap api” is its own question and not just “a domain registrar’s API” is that the Namecheap API has a workflow that other registrar APIs do not have. The workflow is “whitelist your IP, generate the API key, sign every request, parse the XML, handle the rate limit.” The four steps are the same for every endpoint, and the four steps are the part the docs cover in pieces.
Table of contents
- The short version
- The five things to set up before the first API call
- The four endpoints a real automation actually uses
- The three XML request shapes the API expects
- The way the IP whitelist changes the deployment story
- The five mistakes that quietly break a Namecheap API call
- The five-namecheap alternatives a developer should know
- FAQ
The short version
The API is at https://api.namecheap.com/xml.response (production) or https://api.sandbox.namecheap.com/xml.response (sandbox). Every request is a POST with a form-encoded body of named parameters, and the response is an XML document. The request has to be signed with the API key, the request has to come from a whitelisted IP, and the request has to include a unique nonce and a current timestamp. The four constraints are the same for every endpoint, and the four constraints are the part the developer has to get right before the first call returns.
The five things to set up before the first API call
The API is a real API, and the API has a real setup. The five things to set up are the same regardless of the endpoint, the script, or the use case.
Step 1: enable API access in the dashboard. Log in to Namecheap, go to Profile → Tools, and find the Namecheap API Access section. The toggle is off by default. Turn it on. The toggle is the gate that allows the account to make API calls at all.
Step 2: whitelist the IP that will make the API calls. In the same section, add the public IPv4 address of the machine that will be making the calls. The whitelist is per-account, and the API will reject any call from an IP that is not on the list. The whitelist is the part that quietly breaks the first call from a new server.
Step 3: copy the API key. Namecheap generates an API key (a long alphanumeric string) when API access is enabled. The key is shown once, and the developer should store it in a secret manager (1Password, AWS Secrets Manager, environment variables on a managed platform). The key is the authentication for every API call.
Step 4: note the username. The username is the same as the Namecheap account name. The username is sent on every request, along with the API key. The combination of username + API key + IP is the authentication triple, and any of the three being wrong is a request that the API will reject.
Step 5: enable the sandbox (optional but recommended). The sandbox is a separate API endpoint (api.sandbox.namecheap.com) that allows the developer to make test calls without spending money. The sandbox uses fake domains, fake money, and the same API surface. The developer should always test in the sandbox first, and should only move to production after the sandbox calls return the expected responses.
The five steps are the same for every Namecheap API integration. The developer who skips the IP whitelist is the developer who is going to spend an hour debugging an “Invalid API Key” error that is actually an IP whitelist issue.
The four endpoints a real automation actually uses
The API has dozens of endpoints, but a real automation typically uses four. The four are the ones the developer should learn first, and the ones that cover 80% of real use cases.
namecheap.domains.check — check the availability of one or more domains. The request is a list of domain names, the response is a list of available/notavailable/unknown results, and the cost is a single API credit regardless of how many domains are checked. The endpoint is the right answer for a tool that needs to find a domain the user might want to buy.
namecheap.domains.create — register a new domain. The request includes the domain, the years, the contact information, and the nameservers. The response includes the order ID, the charged amount, and the new domain’s expiry date. The endpoint is the right answer for a tool that needs to register a domain on behalf of a user.
namecheap.domains.dns.setHosts — set the DNS records for a domain. The request is a list of host records (A, AAAA, CNAME, MX, TXT, etc.), the response is a confirmation, and the changes propagate across the internet in seconds to hours. The endpoint is the right answer for a tool that needs to point a domain at a service.
namecheap.users.address.getList and the related setDefault calls — manage the contact information that the API uses for new registrations. The API requires a complete contact record before a domain can be registered, and the developer has to set the default address before calling domains.create. The endpoints are the right answer for a tool that needs to register domains on behalf of multiple users.
The four endpoints are the floor. There are also endpoints for transfers (namecheap.domains.transfer.create), for email forwarding (namecheap.domains.dns.setEmailForwarding), for URL forwarding (namecheap.domains.dns.setURLForwarding), and for SSL certificate management (namecheap.ssl.create). The four are the ones the developer should learn first.
The three XML request shapes the API expects
The API is XML for responses, but the requests are form-encoded. The body of a POST request is a set of key-value pairs, and the response is an XML document. The three shapes the developer has to know are:
The standard shape. The body is a set of named parameters: ApiUser, ApiKey, UserName, ClientIp, Command, nonce (a unique string), and Timestamp (a Unix timestamp in seconds). The body is URL-encoded and sent as application/x-www-form-urlencoded. The response is an XML document with an ApiResponse root element, a Status (OK or ERROR), and the command-specific data.
curl -s "https://api.namecheap.com/xml.response" \
-d "ApiUser=myuser" \
-d "ApiKey=my-api-key" \
-d "UserName=myuser" \
-d "ClientIp=1.2.3.4" \
-d "Command=namecheap.domains.check" \
-d "DomainList=example.com" \
-d "nonce=$(uuidgen)" \
-d "Timestamp=$(date +%s)"The bulk shape. Some endpoints (domains.check, domains.dns.setHosts) accept a list of items in a single call. The body uses numbered parameters (DomainList1, DomainList2, DomainList3, or HostName1, HostName2, etc.). The response is the same XML shape, with the per-item result in the body. The shape is the right answer for a tool that needs to check 50 domains or set 20 DNS records in a single call.
The multi-call shape. The API supports a RequestParameters block that lets the developer bundle multiple commands into a single call. The body is a list of commands, each with its own parameters, and the response is a list of command-specific responses. The shape is the right answer for a tool that needs to register a domain, set its DNS, and set up email forwarding in a single API call.
The three shapes are the floor. The developer should always send the nonce and the Timestamp (Namecheap requires both, and rejects calls that omit either), and should always URL-encode the body. The format is not REST, the format is not JSON, and the developer who treats it as REST is the developer who is going to spend an hour debugging a 400 response.
The way the IP whitelist changes the deployment story
The IP whitelist is the part of the Namecheap API that quietly shapes the architecture. The API rejects any call from a non-whitelisted IP, and the whitelist is a list of public IPv4 addresses. The implication is that the developer’s Namecheap API client has to run on a machine with a stable, whitelisted IP — not a serverless function (whose IP changes on every cold start), not a CI runner (whose IP changes per build), not a developer’s laptop (whose IP changes per network).
The typical pattern is a small dedicated VM or a managed platform’s always-on service. A small VM on a provider with a static IP (Hetzner, DigitalOcean, Vultr, Linode, AWS Lightsail) is the right answer for a developer who needs to make Namecheap API calls on a schedule. A managed platform’s always-on service (a worker, a cron job, a long-running container) is the right answer for a developer who is already using a platform.
The pattern is not serverless. AWS Lambda, Vercel Functions, Cloudflare Workers, and Google Cloud Functions all assign ephemeral IPs that the developer cannot whitelist. A serverless function that needs to call the Namecheap API is a function that has to proxy through a dedicated VM, and the VM has to be the one on the whitelist.
The pattern is not a laptop. A developer’s home or office IP changes every time the ISP rotates the address, and the IP is not stable enough to whitelist. The pattern is fine for a one-off test, and the pattern is wrong for a production automation.
The IP whitelist is the part of the Namecheap API that quietly forces a deployment architecture. The developer who knows this before they start is the developer who is going to plan for a stable-IP host. The developer who finds out after the first call is the developer who is going to redesign the architecture.
The five mistakes that quietly break a Namecheap API call
A short, opinionated list of mistakes that have actually broken real Namecheap API integrations. None of them are dramatic. They are the boring ones.
The IP is not whitelisted. A developer who turns on API access but forgets to whitelist the IP is a developer who is going to see an “Invalid API Key” error that is actually an IP whitelist issue. The fix is to whitelist the IP first, and to verify the whitelist is active before the first call.
The ClientIp is not the public IP. The ClientIp parameter has to be the public IP of the machine making the call, not the private IP and not 127.0.0.1. A developer behind a NAT who sends the private IP is a developer who is going to be rejected. The fix is to look up the public IP (curl ifconfig.me or curl ipinfo.io/ip) and send that.
The nonce is reused. The nonce is a unique string per request, and the API rejects requests with a reused nonce. A developer who uses a counter that resets on every script run is a developer who is going to get a “Duplicate request” error. The fix is a UUID, a timestamp with microsecond precision, or a counter that never resets.
The Timestamp is too far in the past. The API rejects requests with a Timestamp more than a few minutes off from the server’s time. A developer whose server clock is drifting is a developer who is going to see a “Timestamp is invalid” error. The fix is to run ntpd or chronyd on the server, or to fetch the current time from an NTP source on every request.
The API key is in the code. A developer who checks the API key into git is a developer who is going to be the subject of a security report. The fix is to put the API key in a secret manager, in environment variables, or in a .env file that is in .gitignore. The same applies to the username and the ClientIp.
The five Namecheap alternatives a developer should know
The Namecheap API is a real API, but it is not the only registrar API a developer can use. The five alternatives that show up in real automations are:
Cloudflare Registrar. The API is REST, the API is JSON, and the API is the same API the developer uses for Cloudflare’s DNS. The advantage is that the developer who is already using Cloudflare for DNS does not have to learn a new API. The disadvantage is that the prices are at-cost (no markup, but no discount either), and the TLD selection is smaller.
Porkbun. The API is REST, the API is JSON, and the API is the same API the developer uses for Porkbun’s dashboard. The advantage is that the prices are competitive, the TLD selection is wide, and the API is straightforward. The disadvantage is that the API documentation is less polished than Namecheap’s.
GoDaddy. The API is REST, the API is JSON (with an older SOAP API still in use), and the API is the same API the developer uses for GoDaddy’s dashboard. The advantage is that the brand is widely recognized, the TLD selection is wide, and the API supports a wide range of operations. The disadvantage is that the API requires an OAuth flow, the documentation is fragmented, and the pricing is on the higher end.
Google Domains (now Squarespace Domains). The API is limited — Squarespace Domains does not have a public API for registration, only for DNS. The advantage is the clean interface. The disadvantage is the lack of automation, which makes it the wrong answer for a developer who needs to register domains programmatically.
Route 53 (AWS). The API is REST, the API is JSON, and the API is part of the AWS API surface. The advantage is that the developer who is already using AWS does not have to learn a new API, and the API supports a wide range of operations. The disadvantage is that the pricing is on the higher end, and the API is the wrong answer for a developer who does not want to be in the AWS ecosystem.
The five alternatives are not exhaustive — there are also Gandi, Hover, OVH, and others — but they are the ones the developer should know. The choice is a function of the developer’s existing stack, the TLDs the developer needs, and the API ergonomics the developer prefers. The developer should not pick a registrar based on the dashboard, and should not pick a registrar based on the marketing. The developer should pick a registrar based on the API.
How this fits the rest of the stack
An API integration rarely lives in isolation. The integration usually runs on a server, authenticates against a service, calls the API, and writes the result to a database. The platform that handles the integration should make the rest of the stack feel like part of the same conversation.
The services layer is the part of the platform that runs the long-lived API the Namecheap integration calls. The database layer is the part that holds the data the integration reads and writes. The static layer is the part that hosts the dashboard where the integration’s status is reported. The environment variables are the part that holds the API key the integration authenticates with.
A Namecheap API integration on a platform where the service, the database, the storage, and the secrets are all in the same place is an integration the team is going to be able to debug. A Namecheap API integration on a platform where each piece is in a different console is an integration the team is going to spend the first hour just opening the right tab.
For a team that wants to see the full cost of the project before it commits, the RunxBuild hosting calculator shows the line items together. The API, the database, the storage, the worker, the bandwidth — each one is a separate number, and the team’s mental model for the platform is the sum of those numbers.
FAQ
What is the Namecheap API?
The Namecheap API is an XML-over-HTTPS surface that lets a developer register, transfer, and manage domains, set DNS records, and check availability — all from a script, a CI job, or a back-office tool. The API is not REST, the API is not JSON, the API is XML with a strict schema and a per-account IP whitelist. The endpoint is https://api.namecheap.com/xml.response (production) or https://api.sandbox.namecheap.com/xml.response (sandbox).
How do I get a Namecheap API key?
Log in to Namecheap, go to Profile → Tools, and find the Namecheap API Access section. Turn on API access, and copy the API key. The key is shown once, and the developer should store it in a secret manager. The key is the authentication for every API call.
Why is my Namecheap API call returning “Invalid API Key”?
The most common cause is the IP whitelist. The API rejects any call from an IP that is not on the whitelist, and the error message is “Invalid API Key” even though the key is fine. The fix is to whitelist the public IP of the machine making the call, and to verify the whitelist is active before the first call.
Can I call the Namecheap API from a serverless function?
Not directly. Serverless functions (AWS Lambda, Vercel Functions, Cloudflare Workers) assign ephemeral IPs that the developer cannot whitelist. The pattern is to proxy the API calls through a dedicated VM with a stable IP, or to use a managed platform’s always-on service. The Namecheap API requires a stable IP because of the IP whitelist.
How do I check domain availability with the Namecheap API?
Call namecheap.domains.check with a list of domains in the DomainList parameter. The response is an XML document with an available/notavailable/unknown result for each domain. The endpoint is the right answer for a tool that needs to find a domain the user might want to buy.
How do I set DNS records with the Namecheap API?
Call namecheap.domains.dns.setHosts with a list of host records (A, AAAA, CNAME, MX, TXT, etc.) in the HostName1, HostName2, etc. parameters. The response is a confirmation, and the changes propagate across the internet in seconds to hours. The endpoint is the right answer for a tool that needs to point a domain at a service.
Is the Namecheap API REST?
No. The API uses form-encoded POST requests with a fixed set of named parameters, and the response is XML. The format is closer to an RPC API than a REST API, and the developer who treats it as REST is the developer who is going to spend an hour debugging a 400 response. The format is documented in the Namecheap API docs, and the developer should follow the format exactly.