> ## Documentation Index
> Fetch the complete documentation index at: https://clearlayer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Register a wallet address for screening.

## Register a wallet

<code>POST /v1/wallets</code>

Registers an Ethereum wallet address and links it to an existing investor. The wallet's screening status and risk level are evaluated by the [decision engine](/api/decisions) when checking compliance against a policy.

<Warning>
  All requests to this endpoint require a valid API key in the `Authorization` header.
</Warning>

***

## Request body

<ParamField path="address" type="string" required>
  The Ethereum wallet address to register (e.g. `"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"`).
</ParamField>

<ParamField path="investor_id" type="string" required>
  The ID of the investor to link this wallet to. The investor must already exist. Returns `404` if not found.
</ParamField>

<ParamField path="screening_status" type="string" required>
  The wallet's screening result. Must be `"verified"`, `"pending"`, or `"blocked"`.
</ParamField>

<ParamField path="risk_level" type="string" required>
  The assessed risk level of the wallet. Must be `"low"`, `"medium"`, or `"high"`.
</ParamField>

***

## Response fields

<ResponseField name="id" type="string">
  Unique wallet ID. Format: `wal_...`
</ResponseField>

<ResponseField name="address" type="string">
  The registered Ethereum wallet address.
</ResponseField>

<ResponseField name="investor_id" type="string">
  The ID of the linked investor.
</ResponseField>

<ResponseField name="screening_status" type="string">
  `"verified"`, `"pending"`, or `"blocked"`.
</ResponseField>

<ResponseField name="risk_level" type="string">
  `"low"`, `"medium"`, or `"high"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the wallet was created.
</ResponseField>

***

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://clearlayer-api-production.up.railway.app/v1/wallets \
    -H "Authorization: Bearer cl_test_key_1234567890" \
    -H "Content-Type: application/json" \
    -d '{
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "investor_id": "inv_a1b2c3d4e5f6",
      "screening_status": "verified",
      "risk_level": "low"
    }'
  ```
</CodeGroup>

### 201 — Created

```json theme={null}
{
  "id": "wal_g7h8i9j0k1l2",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "investor_id": "inv_a1b2c3d4e5f6",
  "screening_status": "verified",
  "risk_level": "low",
  "created_at": "2024-01-15T10:31:00.000Z"
}
```

### 404 — Investor not found

Returned when the `investor_id` does not match any existing investor.

```json theme={null}
{
  "error": "not_found",
  "message": "investor inv_notexist not found",
  "docs": "/investors"
}
```