> ## 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.

# Get agent status and kill-switch state (HMAC or API key)

> <!-- relayer:auth-badge:start -->
> **Auth: agent HMAC or API key.** Accepts the agent's own HMAC credentials (runtime self-call) **or** the integrator's ApiKey (backend query on the agent's behalf).
<!-- relayer:auth-badge:end -->

Returns the agent's current lifecycle status and a `killSwitch` boolean (`true` iff status === 'killed'). Polled every 30s by `@relayerfi/agent-sdk` KillSwitch to gate payment operations. Accepts the agent's own HMAC headers or an integrator API key.



## OpenAPI

````yaml /api-reference/openapi.json get /agents/{id}/status
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/{id}/status:
    get:
      tags:
        - Agents
      summary: Get agent status and kill-switch state (HMAC or API key)
      description: >-
        <!-- relayer:auth-badge:start -->

        > **Auth: agent HMAC or API key.** Accepts the agent's own HMAC
        credentials (runtime self-call) **or** the integrator's ApiKey (backend
        query on the agent's behalf).

        <!-- relayer:auth-badge:end -->


        Returns the agent's current lifecycle status and a `killSwitch` boolean
        (`true` iff status === 'killed'). Polled every 30s by
        `@relayerfi/agent-sdk` KillSwitch to gate payment operations. Accepts
        the agent's own HMAC headers or an integrator API key.
      operationId: AgentController_getAgentStatus
      parameters:
        - name: id
          required: true
          in: path
          description: Agent UUID
          schema:
            type: string
      responses:
        '200':
          description: 'Status payload: `{ agentId, killSwitch, status }`'
        '403':
          description: Agent can only access its own resources
        '404':
          description: Agent not found
      security:
        - bearer: []
      x-codeSamples:
        - lang: bash
          label: cURL (integrator)
          source: |-
            curl https://api.relayer.fi/v1/agents/$AGENT_ID/status \
              -H "Authorization: ApiKey $RELAYER_API_KEY"
        - lang: TypeScript
          label: Node.js (SDK, agent-side)
          source: >-
            import { RelayerSDK } from "@relayerfi/agent-sdk";


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


            // The SDK polls this every 30s automatically via KillSwitch — you
            rarely

            // hit it manually. Use the getter to read the cached state
            synchronously:

            if (sdk.isKillSwitchActive) {
              // skip payment operations
            }


            // Direct call:

            const { data } = await
            sdk.http.get(`/v1/agents/${sdk.agentId}/status`);

            // data.killSwitch (boolean) — true iff status === 'killed'

            // data.status — full lifecycle: active | suspended | draining |
            killed | paused | pending_policies
components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use this format: `ApiKey <your_api_key>`'

````