Integrate our Search API

Integrate the .box Search API into your dApp and earn every time your users purchase a .box domain

How does it work?

• The .box Search API enables your users to search for .box domains through your platform and get redirected to the purchase flow on my.box

• You will be rewarded $18 USDC per domain sold via your platform (15% of our revenue)

If you are interested in becoming a Search API referral partner, don't hesitate to get in touch with us at [email protected] or message our Community Lead, @ohmsdotbox on Telegram

Initial Setup Steps

1. Send the My.box team a wallet address. This wallet address is where your referral rewards will be received

2. Send the My.box team your development environment identifiers to be whitelisted. These will be URLs/IPs depending on your integration approach:

Frontend Integration

Send us your Allowed Origins (URLs) to be configured for frontend access:

1. HTTPS/HTTP and wildcards for subdomains are supported (e.g. *domain.box)

2. Ports for localhost dev access are supported by adding the origin:

   https?://[a-z].?localhost:[0-9]*

Backend Integration

1. Send us your Allowed Servers (IPs) to be configured for server access:

   1. All server access IPV4 (0.0.0.0/0) is supported for development if required

   2. All server access IPV6 (::/0) is supported for development if required

   3. Server IP ranges are supported (ideally to limit access)

1. (Optional) Send us your Allowed Origins (URLs) to be configured for frontend access If your integration also includes a frontend component, we recommend sending us the corresponding URLs to be whitelisted as well for best security practices. See:Frontend Integration

1. (Optional) For testing purposes only: Please advise us if your developers need TEMPORARY API access from their local environments and tools like Postman and we can add a special "allow ALL IPs" configuration: 0.0.0.0/0 Note: this will make our API with your API Key accessible from all IPs. While you are still protected by your dedicated API Key, we recommend that this option be removed as soon as you go live.

1. The My.box team will send you an API key

2. Your team can find the registry.swagger.json file below which can be imported into Postman or Insomnia

9KB

registry.swagger.json

Integrating the Search API

1. Import the Swagger file into Postman or Insomnia

2. Edit the Authorization tab with the provided x-api-key

3. Update the domain query param with the desired domain name to search

Open API 3.0 Spec (swagger)

The open API spec can be imported into Postman for testing the endpoint. Once imported, edit the authorization tab with the provided x-api-key and update the domain query param with the desired domain name you’d like to search

Domain status descriptions:

• “LIVE” Domain is Unavailable and Tokenized. Examples, josh.box, areeb.box, adam.box, ronen.box

• “UNAVAILABLE” - Domain is Unavailable and NOT Tokenized (Reserved/Evergreen, Banned, serverHold, pendingDelete, PendingCreate). Examples, china.box

• “INVALID_DOMAIN” domain name failed validation. Examples, josh--.box, domains >63 chars

• “AVAILABLE” Domain is available for purchase/registration

For domains with the AVAILABLE status, we recommend using the “href” callback URL parameter to route your users to my.box. This will ensure proper referral attribution.

Sample Response - 200 - AVAILABLE domain

{
    "success": true,
    "data": {
        "available": true,
        "domain": "victor1.box",
        "is_premium": false,
        "href": "https://my.box/search?domain=victor1&ref=abc123",
        "status": "AVAILABLE"
    }
}

Sample Response - 200 - LIVE (unavailable and tokenized) domain

{
    "success": true,
    "data": {
        "available": false,
        "domain": "victor.box",
        "is_premium": false,
        "href": "https://my.box/profile/victor.box?ref=abc123",
        "status": "LIVE"
    }
}

Sample Response - 200 - UNAVAILABLE (unavailable and NOT tokenized -banned, reserved) domain

{
    "success": true,
    "data": {
        "available": false,
        "domain": "china.box",
        "is_premium": false,
        "href": "https://my.box?ref=abc123",
        "status": "UNAVAILABLE"
    }
}

Sample Response - 400 - Error

{
    "success": false,
    "error": {
        "code": "ICP_302",
        "message": "Domain query parameter is required"
    }
}

Error Codes (Registry API)

  // Registry API errors
  ICP_301: {
    code: 'ICP_301',
    message: 'API Timeout',
  },
  ICP_302: {
    code: 'ICP_302',
    message: 'Domain query parameter is required',
  },
  ICP_303: {
    code: 'ICP_303',
    message: 'Error checking domain availability',
  },
};

Validation Notes

• Domains can have a total length of 63 characters.

  • i.e., [up-to-63-characters].box

Example Screenshots

1.0: Showing successful response

2.0: Showing error response