> For the complete documentation index, see [llms.txt](https://docs.nullmask.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullmask.io/rpc-api-reference/rpc.md).

# Overview & Authentication

The Nullmask RPC proxy exposes a JSON-RPC interface that wallets connect to as a custom network. It intercepts standard Ethereum methods, provides custom Nullmask methods, and forwards unsupported methods to the underlying blockchain node.

## Authentication

The proxy uses an **access token** to identify users and isolate their private data (keys, notes, transactions).

### Token Generation

The access token is generated during the `nullmask_generateKeys` RPC call:

1. Takes the user's ECDSA signature (from `personal_sign`)
2. Concatenates with salt: `"Nullmask access token"`
3. Hashes with Keccak-256
4. Takes first 16 bytes
5. Encodes as base64url

### Token Delivery

The token is delivered via two mechanisms:

| Mechanism                                  | Priority | Usage                                        |
| ------------------------------------------ | -------- | -------------------------------------------- |
| HTTP-only cookie (`nullmask_access_token`) | Highest  | Set by the proxy on first key generation     |
| Query parameter (`?accessToken=...`)       | Fallback | Embedded in the RPC URL for wallet RPC calls |

### Cookie Attributes

```
httpOnly: true        // JavaScript cannot access (XSS protection)
secure: true          // HTTPS only
sameSite: 'none'      // Allow cross-site requests with credentials
domain: baseDomain    // Accessible to all subdomains
```

### Data Isolation

The access token is combined with the Ethereum address to create isolated storage keys:

```
storageKey = "${accessToken}:${address}".toLowerCase()
```

Different access tokens for the same address result in completely isolated storage.

## CORS Policy

```
origin: true                                    // Accept requests from any origin
credentials: isAllowedOrigin(origin, baseDomain) // Only send cookies to trusted subdomains
```

Untrusted domains cannot access user data because:

1. CORS only allows credentials from trusted subdomains
2. HTTP-only cookies are never sent to untrusted origins
3. Without the cookie, there is no access token
4. Endpoints requiring authentication return 401

## Method Categories

| Category                                                            | Description                                  | Reference                                                                                     |
| ------------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [Modified Ethereum Methods](/rpc-api-reference/modified-methods.md) | Standard methods with privacy-aware behavior | `eth_getBalance`, `eth_sendTransaction`, etc.                                                 |
| [Custom Nullmask Methods](/rpc-api-reference/custom-methods.md)     | Protocol-specific methods                    | `nullmask_generateKeys`, key and balance methods, and the testing-only `nullmask_estimateFee` |
| [Forwarded Methods](/rpc-api-reference/forwarded-methods.md)        | Pass-through to blockchain node              | `eth_gasPrice`, `eth_blockNumber`, etc.                                                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nullmask.io/rpc-api-reference/rpc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.