# Rest API

### Base URL <a href="#base-url" id="base-url"></a>

`<https://api.modular.name/api/public>`

### Key Integration Scenarios <a href="#key-integration-scenarios" id="key-integration-scenarios"></a>

#### 1. Wallet Integration <a href="#id-1.-wallet-integration" id="id-1.-wallet-integration"></a>

Enable users to send transactions using human-readable names instead of addresses.

**Resolve Address by Name**

`GET /identity/address`

**Parameters:**

* `name` (required): Human-readable name to resolve
* `caip2Id` (required): Chain Agnostic ID (e.g., "move-mvmt:testnet")

**Example Request:**

`GET /identity/address?name=alice&caip2Id=move-mvmt:177`

**Example Response:**

`{ "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "resolverAddress": "0x123..." }`

#### 2. Blockchain Explorer Integration <a href="#id-2.-blockchain-explorer-integration" id="id-2.-blockchain-explorer-integration"></a>

Enable reverse lookup of names for addresses displayed in transaction lists and details.

**Batch Resolve Names by Addresses**

`POST /identity/names`

**Request Body:**

`{ "caip2Id": "move-mvmt:testnet", "addresses": [ "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "0x123..." ] }`

**Response:**

`{ "data": { "0x742d35Cc6634C0532925a3b844Bc454e4438f44e": { "name": "alice.snow", "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" } } }`

**Single Address Resolution**

`GET /identity/name`

**Parameters:**

* `address` (required): Address to resolve
* `caip2Id` (required): Chain Agnostic ID

**Example Request:**

`GET /identity/name?address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&caip2Id=move-mvmt:testnet`

**Example Response:**

`{ "name": "alice.snow", "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }`

### Additional Features <a href="#additional-features" id="additional-features"></a>

#### Identity Metadata <a href="#identity-metadata" id="identity-metadata"></a>

Retrieve additional metadata associated with an identity.

`GET /identity/metadata/{name}`

**Parameters:**

* `name` (required): Identity name in path parameter

**Example Request:**

`GET /identity/metadata/alice.snow`

**Example Response:**

`{ "metadata": [ { "key": "avatar", "value": "ipfs://..." } ] }`

#### Batch Address Resolution <a href="#batch-address-resolution" id="batch-address-resolution"></a>

`POST /public-identity/addresses`

**Request Body:**

`{ "caip2Id": "move-mvmt:177", "names": [ "alice.snow", "bob.snow" ] }`

**Response:**

`{ "data": [ { "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "resolverAddress": "0x123..." } ] }`

### CAIP2 ID Format <a href="#caip2-id-format" id="caip2-id-format"></a>

The API uses CAIP2 IDs for chain identification. The format is:

`namespace:reference`

Examples:

* `move-mvmt:177` - Movement `porto` testnet
* `move-mvmt:126` - Movement mainnet
* `move-mvmt:*` - Wildcard for all Movement networks

### Notes on Name Resolution <a href="#notes-on-name-resolution" id="notes-on-name-resolution"></a>

* The API performs reverse lookup from the contract to find the primary name associated with an address
* The owner address is the same as the target address in the resolution process
* When using wildcard CAIP2 IDs (e.g., `move-mvmt:*`), the API will search across all networks in that namespace

### Error Handling <a href="#error-handling" id="error-handling"></a>

The API uses standard HTTP status codes:

* 200: Successful request
* 400: Bad request (invalid parameters or CAIP2 ID)
* 404: Resource not found
* 500: Internal server error

Error Response Format:

`{ "message": "Error message description" }`


---

# Agent Instructions: 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:

```
GET https://snowball-mns.gitbook.io/snowball/decentralized-identity-layer/technical-documentation/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.