Creating Endpoints

How It Works

1. When you create an endpoint, an API key is generated and shown once
2. Add this key to your server's environment variables (e.g., X402_API_KEY)
3. Your server must validate incoming requests using this key
4. The x402 Gateway sends the key in the X-API-Key header

Server-Side Validation Examples

// Node.js / Express
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.X402_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

# Python / Flask
from flask import request, jsonify

@app.before_request
def check_api_key():
    api_key = request.headers.get('X-API-Key')
    if api_key != os.environ.get('X402_API_KEY'):
        return jsonify({'error': 'Unauthorized'}), 401

How the Health Check Works

1. We send a HEAD request to your origin URL (with your API key in headers if configured)
2. If HEAD fails or returns 400+, we retry with a GET request
3. Responses of 2xx, 3xx, or 402 mean your service is up
4. Responses of 401/403 (auth error), 404 (not found), or 5xx (server error) mark the service as unavailable
5. No response within 10 seconds is treated as a timeout

Troubleshooting "Service Unavailable"

• 401/403 error: Your API key is missing or incorrect. Re-check the key in your server's environment variables and make sure it matches what's in the dashboard.
• 404 error: Your origin URL doesn't have a route at the root path. Make sure GET / returns something (even a simple 200 OK).
• Timeout: Your server took longer than 10 seconds to respond. Check if it's running and reachable from the public internet.
• CORS or network error: The health check runs server-side, so CORS isn't the issue. Make sure your server isn't behind a firewall blocking external requests.

Auto-Detect from OpenAPI

If your origin server has an OpenAPI or Swagger spec, x402 Studio will automatically detect it when you enter your origin URL. Detected routes are pre-populated in the form builder.

Manual Builder

1. Click Add Route to add an API route (GET, POST, PUT, etc.)
2. Give it a Service Name — this is what customers see
3. Add Input Fields — each field becomes a form input on the payment page
4. Set labels, placeholders, and whether the field is required
5. Use the Preview toggle to see exactly what customers will see