# Wallets and Faucet API

- **OpenAPI Version:** `3.1.0`
- **API Version:** `1.0.0`

Generate new EVM keys, and retrieve them for a short period via x402. Stored securely, with cache eviction handled by Cloudflare. Optional and recommended: use ephemeral secrets for additional privacy. Open source and transparent.

## Operations

### Get a previously created EOA by public address

- **Method:** `GET`
- **Path:** `/eoa/{address}`

#### Responses

##### Status: 200 Returns an EOA if found

###### Content-Type: application/json

- **`address` (required)**

  `string`

- **`pk` (required)**

  `string`

- **`mnemonic`**

  `string`

**Example:**

```json
{
  "address": "0x1234567890abcdef",
  "pk": "0x1234567890abcdef",
  "mnemonic": "word word ... word"
}
```

##### Status: 404 EOA not found

###### Content-Type: application/json

- **`error` (required)**

  `string`

**Example:**

```json
{
  "error": ""
}
```

### Create a new EOA

- **Method:** `POST`
- **Path:** `/eoa`

#### Request Body

##### Content-Type: application/json

- **`mix_entropy_with_public_source`**

  `boolean` — mix privately generated key with randomness beacon

- **`show_mnemonic`**

  `boolean` — show mnemonic phrase in the response

**Example:**

```json
{
  "mix_entropy_with_public_source": true,
  "show_mnemonic": true
}
```

#### Responses

##### Status: 200 Returns the created EOA

###### Content-Type: application/json

- **`address` (required)**

  `string`

- **`pk` (required)**

  `string`

- **`mnemonic`**

  `string`

**Example:**

```json
{
  "address": "0x1234567890abcdef",
  "pk": "0x1234567890abcdef",
  "mnemonic": "word word ... word"
}
```

### Create ephemeral secrets

- **Method:** `GET`
- **Path:** `/ephemeral-secrets`

#### Responses

##### Status: 200 Generates an ephemeral salt and encryption key

###### Content-Type: application/json

- **`encryption_secret` (required)**

  `string` — Ephemeral encryption key

- **`independent` (required)**

  `boolean` — Whether the salt and encryption key are independent

- **`mixed` (required)**

  `boolean` — Whether the entropy was mixed with a public source

- **`salt` (required)**

  `string` — Ephemeral salt

**Example:**

```json
{
  "salt": "1234567890abcd",
  "encryption_secret": "1234567890123456789012345678901234567890",
  "independent": true,
  "mixed": true
}
```

### Show statistics about the API

- **Method:** `GET`
- **Path:** `/stats`

#### Responses

##### Status: 200 Returns statistics about the API

###### Content-Type: application/json

- **`current_eoa_count` (required)**

  `number` — Current number of EOAs in the database

- **`public_randomness_source` (required)**

  `string` — Public randomness source

- **`time_to_deletion` (required)**

  `number` — Storage time before deletion

- **`total_eoa_created` (required)**

  `number` — Total number of EOAs created

- **`total_eoa_failed_to_decrypt` (required)**

  `number` — Total number of failed requests

- **`total_eoa_retrieved` (required)**

  `number` — Total number of successful requests

- **`user_provided_encryption_key_rules` (required)**

  `string` — Rules for user provided encryption key

- **`user_provided_salt_rules` (required)**

  `string` — Rules for user provided salt

- **`x402_price` (required)**

  `number` — Price per request

**Example:**

```json
{
  "total_eoa_created": 1,
  "total_eoa_retrieved": 1,
  "total_eoa_failed_to_decrypt": 1,
  "current_eoa_count": 1,
  "time_to_deletion": 1,
  "x402_price": 1,
  "public_randomness_source": "",
  "user_provided_salt_rules": "",
  "user_provided_encryption_key_rules": ""
}
```