API Documentation

Complete guide to using the Galaxichain API for building serverless actions

About Galaxichain

Galaxichain is a serverless actions platform designed for the X401/X402 protocol ecosystem. It enables developers to deploy JavaScript functions that automatically react to blockchain events without managing servers or infrastructure.

Built for Web3, Galaxichain uses wallet-based authentication, eliminating the need for traditional API keys and passwords. Simply connect your wallet to get started and deploy actions that respond to MESSAGE, TRANSFER, MINT, and other X401/X402 event types.

Key Features

  • • Serverless JavaScript actions
  • • Wallet-based authentication
  • • Real-time event processing
  • • Built-in logging and monitoring

Use Cases

  • • Automated notifications
  • • Event-driven workflows
  • • Smart contract integrations
  • • Custom business logic

Getting Started

1. Connect Your Wallet

First, connect your Web3 wallet to generate your unique API key. Your wallet address is used as your account identifier.

// In the App dashboard, click "Connect Wallet"
// Your API key will be automatically generated
// Format: ak_<wallet_prefix><random_string>

2. Get Your API Key

After connecting your wallet, navigate to the Overview page to view your API key. Keep it secure!

// Your API key is displayed in the dashboard
// Example: ak_0x1234abcd5678efgh9012ijkl3456mnop

3. Make Your First Request

Use your API key to authenticate requests to the Galaxichain API.

curl -X GET https://api.galaxichain.com/v1/functions \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require authentication using a Bearer token in the Authorization header. Your API key is generated when you connect your wallet and is tied to your wallet address.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://api.galaxichain.com/v1/functions \
  -H "Authorization: Bearer ak_0x1234abcd5678efgh9012ijkl3456mnop" \
  -H "Content-Type: application/json"

Security Note: Never expose your API key in client-side code or public repositories. Use environment variables or secure secret management.

Rate Limits

Rate limits are applied per API key and are based on your account tier. All limits are reset daily at midnight UTC.

Free Tier

  • 1,000 requests/day
  • 5 requests/second
  • 10 actions max

Pro Tier

  • 100,000 requests/day
  • 50 requests/second
  • Unlimited actions

Enterprise

  • Custom limits
  • Custom rate limits
  • Priority support

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Endpoints

GET

List Functions

GET /v1/functions

Retrieve a list of all your deployed functions.

curl -X GET https://api.galaxichain.com/v1/functions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "functions": [
    {
      "id": "func_123",
      "name": "hello-world",
      "version": 1,
      "endpoint": "https://api.galaxichain.com/v1/functions/hello-world/invoke",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}
POST

Create Function

POST /v1/functions

Create a new function with your action code.

curl -X POST https://api.galaxichain.com/v1/functions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "greet",
    "code": "export default async function onAction(ctx) {\n  return { message: \"Hello!\" };\n}"
  }'

Request Body

{
  "name": "greet",
  "code": "export default async function onAction(ctx) {\n  const name = ctx.input?.name || 'World';\n  return { message: `Hello, ${name}!` };\n}"
}
POST

Invoke Function

POST /v1/functions/{id|name}/invoke

Execute a function with an event and input data.

curl -X POST https://api.galaxichain.com/v1/functions/hello-world/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "type": "MESSAGE",
      "payload": { "text": "gm" }
    },
    "input": {
      "name": "Solana"
    }
  }'

Request Body

{
  "event": {
    "type": "MESSAGE",
    "payload": {
      "text": "gm"
    }
  },
  "input": {
    "name": "Solana"
  }
}

Response

{
  "status": "ok",
  "data": {
    "message": "Hello, Solana!"
  },
  "durationMs": 42,
  "invocationId": "inv_123456"
}
GET

Get Logs

GET /v1/logs

Retrieve logs for your functions with filtering options.

curl -X GET "https://api.galaxichain.com/v1/logs?level=info&function=hello-world&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

  • level - Filter by log level (info, warn, error)
  • function - Filter by function name or ID
  • limit - Maximum number of logs to return (default: 50, max: 1000)
  • offset - Pagination offset

Event Types

Galaxichain supports various X401/X402 event types that your functions can react to.

MESSAGE

Triggered when a message is received in the X401/X402 protocol.

{
  "type": "MESSAGE",
  "payload": {
    "text": "Hello, world!",
    "sender": "0x1234...",
    "timestamp": 1640995200
  }
}

TRANSFER

Triggered when a token transfer occurs.

{
  "type": "TRANSFER",
  "payload": {
    "from": "0x1234...",
    "to": "0x5678...",
    "amount": "1000000000000000000",
    "token": "0xabcd..."
  }
}

MINT

Triggered when new tokens are minted.

{
  "type": "MINT",
  "payload": {
    "to": "0x1234...",
    "amount": "5000000000000000000",
    "token": "0xabcd..."
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": {}
  }
}

Common Error Codes

  • INVALID_API_KEY - API key is missing or invalid (401)
  • RATE_LIMIT_EXCEEDED - Rate limit exceeded (429)
  • FUNCTION_NOT_FOUND - Function does not exist (404)
  • EXECUTION_ERROR - Function execution failed (500)
  • VALIDATION_ERROR - Request validation failed (400)

Webhooks

Configure webhooks to receive real-time notifications about function invocations and events.

Setting Up Webhooks

curl -X POST https://api.galaxichain.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["function.invoked", "function.completed"],
    "secret": "your-webhook-secret"
  }'
Try in Playground