Rest API

Base URL

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

Key Integration Scenarios

1. Wallet Integration

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

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

Identity Metadata

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

POST /public-identity/addresses

Request Body:

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

Response:

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

CAIP2 ID Format

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

• 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

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