API quickstart

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

Use the REST API to create a pipeline, add filter values, deploy, and check health.

Setup

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

Authenticate every request with the X-API-Key header. The base URL is https://api.allium.so/api/v1/beam.

Filter USDC transfers on Base

Create the pipeline config

Create a pipeline that streams ERC-20 transfers on Base, filters them by token address, and delivers them to an Allium-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 contains the full BeamConfig, including its generated id.

Get the transform UID

Fetch the config and read the transform’s generated uid. You 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: Allium data stores addresses in lowercase, and matching is exact.

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 equal 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

The values array should contain the USDC address. Data now streams to the beam.${CONFIG_ID}.usdc-transfers topic.

What’s next

Update the pipeline: send the new config to PUT /api/v1/beam/{config_id}, then redeploy. You don’t need to tear down first.
Monitor throughput: call GET /api/v1/beam/{config_id}/deploy/metrics?time_range=1h&aggregated=true for a summary.
Add filter values: post more values to the filter values endpoint at any time, with no redeploy.

API reference

Full endpoint reference

Configuration reference

Source, transform, and sink schemas

Realtime API

Beam API

Explorer API

Account API

Deep Dives

Setup

Filter USDC transfers on Base

What’s next

API reference

Configuration reference

Realtime 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