# EthVanity API Documentation: Ethereum Vanity Jobs

Source: https://www.ethvanity.com/docs/api

Updated: 2026-11-05

Build an asynchronous Ethereum vanity address workflow with EthVanity: submit a pattern, poll the job ID and cancel a search when needed.

Base URL: https://www.ethvanity.com

## Before you integrate

Build an asynchronous Ethereum vanity address workflow with EthVanity: submit a pattern, poll the job ID and cancel a search when needed.

This is the reference for the existing site API, not a separately provisioned public developer platform. Production connectivity is currently awaiting server configuration. A deployed documentation page does not guarantee that generation is available.

There is no documented customer API-key provisioning flow or service-level agreement. The server-to-server gateway credential is private and is never supplied to clients. If site access or verification is required, complete the supported site flow before making requests.

- Use the HTTPS origin of this site for all three operations.
- Examples are illustrative and do not execute a search on this page.
- Browser examples are intended for the same site origin. Cross-origin access from another website is not guaranteed.

## Start small, keep the job ID

Use a short Ethereum pattern for an initial integration. A successful submission returns a jobId; it does not mean an address has been found.

Do not automatically retry a timed-out start request: the first request may already have created a job.


```bash
curl --request POST 'https://www.ethvanity.com/api/start-job' \
  --header 'Content-Type: application/json' \
  --data '{"prefix":"abc"}'
```


Example response:

```json
{
  "jobId": "example-job-id"
}
```

**POST /api/start-job**

## Start a generation job

Send a JSON object. Pattern validation occurs before the job is submitted. Do not include the display ellipsis in a prefix or suffix.


| Field | Type | Required | Rules |
| --- | --- | --- | --- |
| prefix | string | Optional; at least one pattern is required. | 1–7 hexadecimal characters, without 0x. |
| suffix | string | Optional; at least one pattern is required. | 1–7 hexadecimal characters. Do not combine with prefix. |
| turnstileToken | string | When requested by the site verification flow. | Use the token issued by that flow; do not hardcode or reuse a token. |
| referrer | string | Optional. | The site proxy may replace this with captured attribution. It is not authentication. |


## Ethereum pattern rules

Ethereum patterns contain only 0–9, a–f or A–F. The start endpoint accepts one prefix or one suffix, with a length of 1–7 characters. Omit the 0x marker from the request.

Letter case is accepted in input, but this contract does not promise a checksum-case match. This endpoint searches wallet addresses; it does not assign an ENS name or calculate a CREATE2 contract address.

- Quotes, whitespace, SQL expressions and punctuation are not valid address patterns.
- A matching address is not proof of identity or ownership. Verify the entire address before using it.

**GET /api/check-status?id={jobId}**

## Read the job state

Pass the jobId from the start response as the id query parameter. A pending response means the search has not produced a terminal result.

A completed response has status "completed" and a result object returned by the generation service. Treat result as sensitive: it can contain key material. This reference does not guarantee a stable field-level result schema.

A cancelled job returns status "cancelled". An unknown job returns 404; jobs are tracked in memory and may disappear after a service restart.


```bash
curl 'https://www.ethvanity.com/api/check-status?id=example-job-id'
```


Example response:

```json
{
  "status": "pending"
}
```

**POST /api/cancel-job**

## Cancel a search

Use id in the JSON body, not jobId. A successful response confirms cancellation handling, not guaranteed immediate termination of every upstream computation.

Repeated cancellation may return "Already cancelled". The service may report "Cancelled locally" if the upstream cancellation call fails. Cancelling a completed job returns 400.


```bash
curl --request POST 'https://www.ethvanity.com/api/cancel-job' \
  --header 'Content-Type: application/json' \
  --data '{"id":"example-job-id"}' 
```


Example response:

```json
{
  "success": true,
  "message": "Cancelled"
}
```

## JavaScript integration

This example submits once, polls every three seconds and requests cancellation after a two-minute client deadline. These are example client choices, not a promised server timeout or rate limit.

Run it in a server environment with fetch support or from the same site origin with the required session and verification context. A network failure still requires explicit handling in your application.


```javascript
const base = "https://www.ethvanity.com";
const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
async function request(path, options = {}) {
  const response = await fetch(base + path, {
    ...options, signal: AbortSignal.timeout(15000)
  });
  if (!response.ok) throw new Error(`API request failed (${response.status})`);
  return response.json();
}
async function findAddress() {
  const { jobId } = await request("/api/start-job", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prefix: "abc" })
  });
  const deadline = Date.now() + 120000;
  while (Date.now() < deadline) {
    await pause(3000); // Suggested client interval, not a server quota.
    const job = await request("/api/check-status?id=" + encodeURIComponent(jobId));
    if (job.status === "completed") return job.result; // Do not log secrets.
    if (job.status === "cancelled") throw new Error("Search cancelled");
    if (job.status !== "pending") throw new Error("Unexpected job state");
  }
  await request("/api/cancel-job", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: jobId })
  });
  throw new Error("Client deadline reached; cancellation requested");
}
```


## Errors and retry behavior

Inspect the HTTP status before treating a response as a job result. The site gateway may normalize upstream failures to a generic 502 response. Error wording is not a stable integration contract.


| HTTP status | Meaning | Client action |
| --- | --- | --- |
| 400 | Invalid JSON, pattern, field type or job operation. | Correct the request before retrying. |
| 403 | Access or verification refused. | Use the supported access/verification flow; do not bypass it. |
| 404 | Unknown route or job ID. | Check the ID and site; a restart can remove job history. |
| 415 | A JSON POST was sent without application/json. | Set the Content-Type header. |
| 429 | A throttling control rejected the request. | Back off; honor Retry-After if supplied. |
| 500 / 502 | Generation failure, upstream timeout or gateway error. | Stop polling a failed job. Avoid blind resubmission. |
| 503 | Required production gateway configuration is missing. | Wait for the operator to restore the service. |


## Limits, timeouts and reliability

No public request quota or guaranteed completion time is currently documented for these job endpoints. Do not assume that limits on browser telemetry also apply to job creation.

Use one active request at a time, a bounded polling loop and an explicit cancellation flow. A request timeout is different from a generation timeout: the search may still be running when a client request ends.

The examples do not provide durable job recovery, idempotency keys or a webhook subscription API. Do not build around features that are not part of this contract.


## Handle results privately

Never send an existing funded wallet’s private key or seed phrase to the job endpoints. Starting a job requires a pattern, not an existing wallet secret.

Generation results may contain sensitive key material and the backend can retain generation records. Do not log result objects, include them in analytics, or expose them in error reports. Review the site privacy policy before using the service.

The browser telemetry endpoint is internal to the site and is intentionally not part of this integration reference.

- [Read the privacy policy](https://www.ethvanity.com/privacy)
- [Read the terms of service](https://www.ethvanity.com/terms)
- [Understand Ethereum vanity addresses](https://www.ethvanity.com/guide)