API quickstart

Prerequisites: You need an Allium API key. Get one from app.allium.so/settings/api-keys.

This guide walks through the full lifecycle of a Beam pipeline using the REST API: create a config, populate filter values, deploy, and check health.

Setup

export ALLIUM_API_KEY="your-api-key-here"

All requests use the X-API-Key header for authentication against the base URL https://api.allium.so/api/v1/beam.

Filter USDC transfers on Base

Create the pipeline config

Create a pipeline that streams ERC20 transfers on Base, filtered by token address using a Redis set filter, and outputs to a managed Kafka topic.

RESP=$(curl -s -X POST https://api.allium.so/api/v1/beam \
  -H "X-API-Key: ${ALLIUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "USDC Transfer Monitor",
    "description": "Monitors USDC ERC20 transfers on Base",
    "tags": ["quickstart"],
    "pipeline_config": {
      "source": {
        "type": "pubsub",
        "chain": "base",
        "entity": "erc20_token_transfer",
        "is_zerolag": false
      },
      "transforms": [
        {
          "type": "redis_set_filter",
          "filter_expr": "root = this.token_address"
        }
      ],
      "sinks": [
        {
          "type": "kafka",
          "name": "usdc-transfers"
        }
      ]
    }
  }')
echo "Response is $RESP" | jq
CONFIG_ID=$(echo "$RESP" | jq -r '.id')
echo "CONFIG_ID=${CONFIG_ID}"

The response returns the full BeamConfig with a generated id.

Get the transform UID

Fetch the config to extract the auto-generated transform UID — you’ll need it to manage filter values.

RESP=$(curl -s -X GET "https://api.allium.so/api/v1/beam/${CONFIG_ID}" \
  -H "X-API-Key: ${ALLIUM_API_KEY}")

TRANSFORM_UID=$(echo "$RESP" | jq -r '.pipeline_config.transforms[0].uid')
echo "TRANSFORM_UID=${TRANSFORM_UID}"

Add filter values

Add the USDC contract address on Base. Use lowercase — values are normalized in the system.

curl -s -X POST https://api.allium.so/api/v1/beam/${CONFIG_ID}/transforms/${TRANSFORM_UID}/filter-values \
  -H "X-API-Key: ${ALLIUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "values": ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"] }' | jq

Expected: { "added": 1 }

Deploy

curl -s -X POST https://api.allium.so/api/v1/beam/${CONFIG_ID}/deploy \
  -H "X-API-Key: ${ALLIUM_API_KEY}" | jq

Expected: {"message": "Pipeline <CONFIG_ID> successfully deployed"}

Check deployment health

curl -s -X GET https://api.allium.so/api/v1/beam/${CONFIG_ID}/deploy/stats \
  -H "X-API-Key: ${ALLIUM_API_KEY}" | jq

healthy_workers should match total_workers. If workers are still starting, wait a few seconds and retry.

Verify filter values

curl -s -X GET "https://api.allium.so/api/v1/beam/${CONFIG_ID}/transforms/${TRANSFORM_UID}/filter-values?count=10" \
  -H "X-API-Key: ${ALLIUM_API_KEY}" | jq

You should see your USDC address in the values array. Data is now streaming to beam.${CONFIG_ID}.usdc-transfers.

What’s next

Update your pipeline — modify the config with PUT /api/v1/beam/{config_id}, then redeploy. No need to teardown first.
Monitor metrics — use GET /api/v1/beam/{config_id}/deploy/metrics?time_range=1h&aggregated=true for a throughput summary.
Add more filter values — post additional addresses to the filter values endpoint at any time (no redeploy needed).

API reference

Full endpoint reference

Configuration reference

Source, transform, and sink schemas

Realtime API

Stream Transformation API

Beam API

Explorer API

Account API

Deep Dives

Setup

Filter USDC transfers on Base

What’s next

API reference

Configuration reference

​Setup

​Filter USDC transfers on Base

​What’s next

API reference

Configuration reference

Setup

Filter USDC transfers on Base

What’s next