# 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" }`