docs.my.box
Launch AppDiscordX
  • Get Started
    • Welcome
  • Get a .box
    • Purchase a .box Domain
    • Purchase with MetaMask mobile
    • Insufficient Funds
      • "I do not have enough funds on Optimism, but I do have enough funds on another network"
      • "I do not have enough funds on any network"
      • "I don't know what the issue is — help!"
  • Configure your .box
    • What now?
    • Configure DNS
      • Set up your website
      • Set up a subdomain
      • Set up a redirect
      • Set Up External Email Provider
        • Configure Email
      • Set up a for-sale lander with all.box
      • Set up Nameserver Forwarding/Delegation
      • DNS Record Examples
    • Configure ENS
      • Set Primary ENS Name
      • Set Avatar
      • Set ENS Records
      • Forward & Reverse Resolution
      • Transfer .box domain
  • Resources
    • Brand Kit
    • Domain Expiration
    • Contact Support
    • Earn with .box
    • Integrate our Search API
    • Learn
      • Trademark and UDRP
      • .box Domains & Optimism
      • Domain security
      • Glossary
    • FAQ
      • Why don't I see my .box domain NFT on OpenSea?
      • Why am I receiving an error saying that I have insufficient funds?
      • Why are some .box domains not available for registration?
      • Why does a domain appear as unavailable but its profile page says it "could be yours"?
      • I made a DNS change, why is it not appearing?
      • Why is my domain missing in My Domains on my.box?
      • Why is there an alert on my .box NFT?
      • What is WHOIS Information?
Powered by GitBook
On this page
  • How does it work?
  • Initial Setup Steps
  • Integrating the Search API
  • Example Screenshots
  1. Resources

Integrate our Search API

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

PreviousEarn with .boxNextLearn

Last updated 5 months ago

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 or message our Community Lead, 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

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

hello@my.box
@ohmsdotbox
9KB
registry.swagger.json
1.0: Showing successful response
2.0: Showing error response