> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayer.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch ingest agent events (up to 100)

> <!-- relayer:auth-badge:start -->
> **Auth: agent HMAC.** Called by the agent SDK at runtime with `x-agent-id`, `x-agent-auth`, `x-request-timestamp` headers. **Not callable from backend ApiKey.** See [Authentication → Agent HMAC](/get-started/authentication).
<!-- relayer:auth-badge:end -->



## OpenAPI

````yaml /api-reference/openapi.json post /agents/events/batch
openapi: 3.0.0
info:
  title: Relayer
  description: >-
    Relayer API — Kit-based crypto infrastructure for OTC exchange, wallet
    signing, payouts, and widget actions.
  version: '1.0'
  contact: {}
servers:
  - url: https://testnet.relayer.fi/v1
    description: Sandbox (testnet wallets, no real fiat)
  - url: https://api.relayer.fi/v1
    description: Production (mainnet wallets, regulated fiat rails)
security:
  - api-key: []
tags:
  - name: 'Action: Builders'
    description: Transaction metadata builders
  - name: 'Action: Directory'
    description: Widget directory
  - name: 'Action: Execute'
  - name: 'Action: Tokens'
    description: Token lists per chain/protocol
  - name: Addresses
  - name: Agents
  - name: App
    description: Application endpoints
  - name: 'Payout: Accounts'
    description: Payment execution
  - name: 'Payout: Off-ramp'
  - name: 'Payout: On-ramp'
  - name: 'Payout: Orders'
  - name: 'Payout: Recipients'
    description: Beneficiary management
  - name: Signing - Passkeys
  - name: Signing - Recovery
  - name: Signing Approvals
    description: Transaction signing approvals
  - name: Signing Policies
    description: Signing policy management
  - name: Transactions
    description: Transaction signing and broadcasting
  - name: Wallets
    description: Wallet and address management
paths:
  /agents/events/batch:
    post:
      tags:
        - Agents
      summary: Batch ingest agent events (up to 100)
      description: >-
        <!-- relayer:auth-badge:start -->

        > **Auth: agent HMAC.** Called by the agent SDK at runtime with
        `x-agent-id`, `x-agent-auth`, `x-request-timestamp` headers. **Not
        callable from backend ApiKey.** See [Authentication → Agent
        HMAC](/get-started/authentication).

        <!-- relayer:auth-badge:end -->
      operationId: AgentController_batchEvents
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEventsDto'
      responses:
        '200':
          description: Events recorded successfully
        '400':
          description: Invalid events payload
        '401':
          description: Invalid agent credentials
      security:
        - bearer: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # Agent endpoints require HMAC-SHA256 signing. See

            # /get-started/authentication for the full payload + headers spec,
            or use

            # the @relayerfi/agent-sdk which signs automatically.


            curl -X POST https://api.relayer.fi/v1/agents/events/batch \
              -H "x-agent-id: $AGENT_ID" \
              -H "x-agent-auth: $HMAC_SIGNATURE_HEX" \
              -H "x-request-timestamp: $UNIX_TS" \
              -H "Content-Type: application/json" \
              -d '{
                "events": [
                  { "type": "llm_call",  "tokens": 1234, "cost_usd": "0.018" },
                  { "type": "api_call",  "endpoint": "https://example/api", "cost_usd": "0.001" },
                  { "type": "payment",   "amount": "5.00", "currency": "USDC", "to": "skill_xyz" }
                ]
              }'
        - lang: TypeScript
          label: Node.js (SDK)
          source: >-
            import { RelayerSDK } from "@relayerfi/agent-sdk";


            const sdk = new RelayerSDK({ /* ... */ });


            // The SDK batches automatically. Manual flush:

            sdk.emitEvent({ type: "llm_call", tokens: 1234, cost_usd: "0.018"
            });

            sdk.emitEvent({ type: "api_call", endpoint: "https://example/api",
            cost_usd: "0.001" });

            sdk.emitEvent({ type: "payment", amount: "5.00", currency: "USDC",
            to: "skill_xyz" });


            // EventBatcher flushes every 10s by default (configurable).

            // Up to 100 events per batch. Selective retry: 429/5xx retried, 4xx
            dropped.
components:
  schemas:
    BatchEventsDto:
      type: object
      properties:
        events:
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/BatchEventItemDto'
      required:
        - events
    BatchEventItemDto:
      type: object
      properties:
        type:
          type: string
          description: Event type (open-ended text)
          example: llm_call
        amount:
          type: number
          description: Amount in USD (for budget-relevant events)
        recipient:
          type: string
          description: Recipient address or identifier
        metadata:
          type: object
          description: Arbitrary metadata
      required:
        - type
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use this format: `ApiKey <your_api_key>`'

````