> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.caesar.xyz/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server. # x402 Payments Caesar supports [x402](https://x402.gitbook.io/x402) so you can pay for research jobs per request without pre-provisioning an API key. The `/x402/research` endpoint verifies an x402 payment, creates a scoped API key that only works for the resulting ask, and returns that secret in the response. You can then call any standard Caesar endpoint with that key to retrieve results or fetch content. > **Note** > > x402 is fully self-serve: you provide a signed payment payload in the `X-PAYMENT` header, Caesar verifies/settles it with the facilitator, and you instantly receive a temporary key for that ask. ## How the flow works 1. **Prepare an x402 payment payload** using your wallet or facilitator client (see the [x402 quickstart](https://x402.gitbook.io/x402) for language-specific helpers). 2. **POST to `/x402/research`** with the payment payload and your research request. 3. **Receive a response** containing the research job ID, status, and a temporary `api_key_secret`. 4. **Use the returned API key** as a Bearer token to call standard Caesar endpoints (e.g., `GET /research/{id}` or `GET /research/{id}/results/{resultId}/content`). 5. Once the research completes, **revoke the key** (it is already scoped to the single ask and expires automatically after settlement). > **Warning** > > The `api_key_secret` returned from `/x402/research` is the only time the secret is shown. Store it securely if you need to poll for results. ## Requesting research with x402 ### Request POST [https://api.caesar.xyz/x402/research](https://api.caesar.xyz/x402/research) ```curl curl -X POST https://api.caesar.xyz/x402/research \ -H "X-PAYMENT: X-PAYMENT" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the latest advancements in renewable energy technologies?" }' ``` ```python import requests url = "https://api.caesar.xyz/x402/research" payload = { "query": "What are the latest advancements in renewable energy technologies?" } headers = { "X-PAYMENT": "X-PAYMENT", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.caesar.xyz/x402/research'; const options = { method: 'POST', headers: {'X-PAYMENT': 'X-PAYMENT', 'Content-Type': 'application/json'}, body: '{"query":"What are the latest advancements in renewable energy technologies?"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.caesar.xyz/x402/research" payload := strings.NewReader("{\n \"query\": \"What are the latest advancements in renewable energy technologies?\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-PAYMENT", "X-PAYMENT") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.caesar.xyz/x402/research") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-PAYMENT"] = 'X-PAYMENT' request["Content-Type"] = 'application/json' request.body = "{\n \"query\": \"What are the latest advancements in renewable energy technologies?\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.caesar.xyz/x402/research") .header("X-PAYMENT", "X-PAYMENT") .header("Content-Type", "application/json") .body("{\n \"query\": \"What are the latest advancements in renewable energy technologies?\"\n}") .asString(); ``` ```php request('POST', 'https://api.caesar.xyz/x402/research', [ 'body' => '{ "query": "What are the latest advancements in renewable energy technologies?" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-PAYMENT' => 'X-PAYMENT', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.caesar.xyz/x402/research"); var request = new RestRequest(Method.POST); request.AddHeader("X-PAYMENT", "X-PAYMENT"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"What are the latest advancements in renewable energy technologies?\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-PAYMENT": "X-PAYMENT", "Content-Type": "application/json" ] let parameters = ["query": "What are the latest advancements in renewable energy technologies?"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.caesar.xyz/x402/research")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` The endpoint accepts the same body as `POST /research`. The key difference is the required `X-PAYMENT` header: ```http POST /x402/research HTTP/1.1 Host: api.caesar.xyz Content-Type: application/json X-PAYMENT: {{base64-encoded x402 payload}} { "query": "Summarise the latest trends in agentic tooling for autonomous research", "compute_units": 2, "system_prompt": "Return a concise executive summary with bullet-point recommendations." } ``` The service verifies the payment, settles it, enqueues the ask, and returns the temporary key: ```json { "id": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10", "status": "queued", "api_key_secret": "sk-temp-x402-demo-secret" } ``` ## Using the scoped API key Treat the returned `api_key_secret` exactly like a normal Caesar API key, but remember it is scoped to a single ask. Any request that references the original ask ID will succeed; other operations will be rejected. **`Poll status`** ```bash Poll status curl "https://api.caesar.xyz/research/f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10" \ -H "Authorization: Bearer sk-temp-x402-demo-secret" ``` **`Fetch content`** ```bash Fetch content curl "https://api.caesar.xyz/research/f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10/results/3b1d.../content" \ -H "Authorization: Bearer sk-temp-x402-demo-secret" ``` ## Troubleshooting #### 402 Payment required Ensure the `X-PAYMENT` header is present and correctly base64-encoded. The payload must match the price quoted by the endpoint; out-of-date or reused payloads are rejected. #### 401 Unauthorized after using the secret The secret only authorizes access to the ask it created. Verify you are calling endpoints with the same ask ID returned by `/x402/research`. #### Need higher compute budget Increase `compute_units` in the request body. The x402 charge scales with the units you specify. ## Additional resources #### [x402 protocol docs](https://x402.gitbook.io/x402) Deep dive into payment payloads, facilitator configuration, and supported chains. #### [Caesar API reference](/api-reference#operation/createResearchObjectX402) View the OpenAPI definition for `/x402/research`, including request/response schemas. > **Note** > > Looking for a higher-level walkthrough? The [Firecrawl x402 documentation](https://docs.firecrawl.dev/x402/search) is a great companion piece that illustrates similar flows. >