hotel_search

Search current hotel inventory and return normalized full-stay room rates and cancellation information.

When to use

Use when an agent needs hotel search from current travel offers.

Selection guidance

Role: supporting. Use when an agent needs hotel search from current travel offers.

Use cases

Access

Price: $0.10 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.

Get the full result

0.10 USD per call

Try free preview · limited information, no charge
curl -X POST 'https://api.rafidsystem.com/api/v1/preview/hotel_search' -H 'Content-Type: application/json' --data '{"destination":"Dubai","checkIn":"2026-11-12","checkOut":"2026-11-15","nationality":"OM","currency":"USD"}'
Pay with USDC · request an x402 challenge
curl -X POST 'https://api.rafidsystem.com/api/v1/x402/travel/hotel-search' -H 'Content-Type: application/json' --data '{"destination":"Dubai","checkIn":"2026-11-12","checkOut":"2026-11-15","nationality":"OM","currency":"USD"}'
Authorized x402 client · signed retry request
curl -X POST 'https://api.rafidsystem.com/api/v1/x402/travel/hotel-search' -H 'Content-Type: application/json' -H 'PAYMENT-SIGNATURE: <PAYMENT_SIGNATURE_FROM_AUTHORIZED_CLIENT>' -H 'X-Rafid-Payment-Journey: <PAYMENT_JOURNEY_FROM_CHALLENGE>' -H 'Idempotency-Key: <UNIQUE_REQUEST_ID>' --data '{"destination":"Dubai","checkIn":"2026-11-12","checkOut":"2026-11-15","nationality":"OM","currency":"USD"}'

Use an x402-compatible client to parse PAYMENT-REQUIRED and authorize payment before retrying the same input with PAYMENT-SIGNATURE. Copying a request does not pay.

No crypto wallet? Use Rafid Credits
curl -X POST 'https://api.rafidsystem.com/api/v1/travel/hotel-search' -H 'Content-Type: application/json' -H 'Authorization: Bearer <RAFID_API_KEY>' -H 'X-Rafid-Payment-Method: credits' -H 'Idempotency-Key: <UNIQUE_REQUEST_ID>' -H 'X-Rafid-Payment-Journey: <PAYMENT_JOURNEY_FROM_CHALLENGE>' --data '{"destination":"Dubai","checkIn":"2026-11-12","checkOut":"2026-11-15","nationality":"OM","currency":"USD"}'

Credits onboarding not yet self-service. Obtain a Rafid account and API key from the operator; existing accounts can use configured funding routes.

Existing account balance: GET https://api.rafidsystem.com/api/v1/account/balance.

MCP Credits integration
POST https://api.rafidsystem.com/mcp/credits
Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Idempotency-Key: <UNIQUE_REQUEST_ID>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hotel_search",
    "arguments": {
      "destination": "Dubai",
      "checkIn": "2026-11-12",
      "checkOut": "2026-11-15",
      "nationality": "OM",
      "currency": "USD"
    }
  }
}

OAuth metadata: authorization server · protected resource. Operator authorization and an existing funded account are required; OAuth does not grant credits.

Payment instructions and onboarding · API docs and schemas

These are copyable API integration requests. They do not open a checkout or execute a paid tool.

Related tools

Example input

{
  "destination": "Dubai",
  "checkIn": "2026-11-12",
  "checkOut": "2026-11-15",
  "nationality": "OM",
  "currency": "USD"
}

Example output

{
  "destination": {
    "query": "Dubai",
    "resolvedName": "Dubai"
  },
  "hotels": [],
  "count": 0,
  "searchedAt": "2026-10-04T00:00:00.000Z",
  "provider": {
    "name": "letsfg",
    "status": "ok",
    "upstreamLatencyMs": 0
  },
  "dataMode": "live"
}

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "pattern": "^[\\p{L}\\p{N} .,'()-]+$"
    },
    "checkIn": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "checkOut": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "adults": {
      "default": 1,
      "type": "integer",
      "minimum": 1,
      "maximum": 9
    },
    "children": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 8
    },
    "childAges": {
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 17
      }
    },
    "currency": {
      "default": "USD",
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "nationality": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "destination",
    "checkIn",
    "checkOut",
    "adults",
    "children",
    "childAges",
    "currency",
    "nationality",
    "limit"
  ],
  "additionalProperties": false
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "destination": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "resolvedName": {
          "type": "string"
        }
      },
      "required": [
        "query",
        "resolvedName"
      ],
      "additionalProperties": false
    },
    "hotels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "stars": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0,
                "maximum": 5
              },
              {
                "type": "null"
              }
            ]
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "roomName": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "price": {
                  "type": "object",
                  "properties": {
                    "amount": {
                      "type": "number",
                      "minimum": 0
                    },
                    "currency": {
                      "type": "string",
                      "pattern": "^[A-Z]{3}$"
                    }
                  },
                  "required": [
                    "amount",
                    "currency"
                  ],
                  "additionalProperties": false
                },
                "refundable": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "freeCancellationUntil": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "cancellationPolicy": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "provider": {
                  "type": "string",
                  "const": "letsfg"
                }
              },
              "required": [
                "id",
                "roomName",
                "price",
                "refundable",
                "freeCancellationUntil",
                "cancellationPolicy",
                "provider"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "name",
          "stars",
          "offers"
        ],
        "additionalProperties": false
      }
    },
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "searchedAt": {
      "type": "string"
    },
    "provider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "const": "letsfg"
        },
        "status": {
          "type": "string",
          "const": "ok"
        },
        "upstreamLatencyMs": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "name",
        "status",
        "upstreamLatencyMs"
      ],
      "additionalProperties": false
    },
    "dataMode": {
      "type": "string",
      "const": "live"
    }
  },
  "required": [
    "destination",
    "hotels",
    "count",
    "searchedAt",
    "provider",
    "dataMode"
  ],
  "additionalProperties": false
}

Category: travel · hierarchy: supporting · idempotent: yes · side effects: no