Deploy ERC-8004 Autonomous Agent — POST /api/agent/deploy

Deploying an agent through FlareHQ does three things in a single API call: it provisions two Smart Contract Account (SCA) wallets (one owner, one validator), registers the agent’s identity in the ERC-8004 Identity Registry on Arc testnet, and persists the agent record to your merchant account. The response contains everything you need to start making agent-authenticated x402 payments — the ERC-8004 tokenId, both wallet addresses, and the on-chain transaction hash.

This endpoint requires a merchant Bearer token. You can generate one in the FlareHQ dashboard under Settings → API Keys.

Request

POST https://flarehq.xyz/api/agent/deploy

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer fhq_sec_...` — your merchant API key
`Content-Type`	Yes	`application/json`

Body Parameters

All body parameters are optional. The endpoint will deploy a functional agent with sensible defaults if you send an empty body ({}).

string

default:"FlareHQ Autonomous Agent"

A human-readable display name for the agent. Stored in the FlareHQ agent registry and shown in the dashboard. Maximum 120 characters.

string

IPFS (ipfs://baf...) or HTTPS URI pointing to a JSON document that describes the agent’s capabilities, supported APIs, and pricing. This URI is written directly into the ERC-8004 Identity Registry on-chain.

Show Recommended metadata schema

{
  "name": "DeFi Analytics Agent",
  "description": "Queries on-chain DeFi data across multiple protocols.",
  "capabilities": ["price-feed", "liquidity-analysis"],
  "version": "1.0.0"
}

string

Ethereum address of the operator who controls this agent. Stored in the ERC-8004 Identity Registry. Defaults to a FlareHQ-managed address if omitted — override this in production with your own address.

Response

200 — Success

boolean

true when both wallets were provisioned and the on-chain registration confirmed.

object

The full agent record as persisted to the FlareHQ registry database.

Show agent fields

string

The display name you provided (or the default).

string

The ERC-8004 NFT token ID assigned by the Identity Registry contract. Use this as the {tokenId} component of your agent identifier (8004:5042002:{tokenId}).

string

Primary Circle SCA wallet address for this agent. Fund this address with test USDC to enable x402 payments.

string

The Circle platform UUID for the owner SCA wallet. Use this when calling Circle APIs directly.

string

Deployment status. Returns "ACTIVE_AGENT_PROVISIONED" on success.

string

The FlareHQ merchant account ID that owns this agent. Useful for associating agents with specific merchant accounts in multi-tenant setups.

string

Arc testnet transaction hash for the ERC-8004 register() call. Confirms the agent’s identity is now live on-chain.

string

Direct ArcScan link to the registration transaction (https://testnet.arcscan.app/tx/{txHash}).

object

Both wallet addresses created during provisioning.

Show wallets fields

string

Address of the owner SCA wallet — this is the same as agent.scaAddress. It is the primary spending wallet for x402 payments.

string

Address of the validator SCA wallet. Per ERC-8004, the validator is a separate identity used to record reputation feedback. It must differ from the owner wallet.

500 — Server Error

Returned when agent provisioning fails due to a server-side error or when on-chain registration is rejected.

{
  "error": "Internal Server Error"
}

408 — Timeout

Returned when the on-chain registration transaction does not confirm within the expected window.

{
  "error": "Transaction polling timed out"
}

Examples

curl -X POST https://flarehq.xyz/api/agent/deploy \
  -H "Authorization: Bearer fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "DeFi Analytics Agent",
    "metadataUri": "ipfs://bafkreibdi...",
    "ownerNode": "0xYourAddress"
  }'

const res = await fetch("https://flarehq.xyz/api/agent/deploy", {
  method: "POST",
  headers: {
    Authorization: "Bearer fhq_sec_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentName: "DeFi Analytics Agent",
    metadataUri: "ipfs://bafkreibdi...",
    ownerNode: "0xYourAddress",
  }),
});

const { agent, txHash, wallets } = await res.json();
console.log(`Agent deployed: 8004:5042002:${agent.tokenId}`);
console.log(`Fund at: ${agent.scaAddress}`);

import requests

res = requests.post(
    "https://flarehq.xyz/api/agent/deploy",
    headers={
        "Authorization": "Bearer fhq_sec_test_...",
        "Content-Type": "application/json",
    },
    json={
        "agentName": "DeFi Analytics Agent",
        "metadataUri": "ipfs://bafkreibdi...",
        "ownerNode": "0xYourAddress",
    },
)
data = res.json()
print(f"Token ID: {data['agent']['tokenId']}")
print(f"SCA Address: {data['agent']['scaAddress']}")

Success Response

{
  "success": true,
  "agent": {
    "name": "DeFi Analytics Agent",
    "tokenId": "68210",
    "scaAddress": "0xA1B2C3D4E5F6...",
    "circleWalletId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ownerNode": "0xYourAddress",
    "metadataURI": "ipfs://bafkreibdi...",
    "status": "ACTIVE_AGENT_PROVISIONED",
    "merchantId": "merch_01HZ..."
  },
  "txHash": "0xabc123def456...",
  "explorerUrl": "https://testnet.arcscan.app/tx/0xabc123def456...",
  "wallets": {
    "owner": "0xA1B2C3D4E5F6...",
    "validator": "0x9F8E7D6C5B4A..."
  }
}

Next Steps After Deployment

Once deployment succeeds, follow these steps before making your first x402 payment: 1. Fund the agent’s SCA wallet with test USDC Visit faucet.circle.com, select ARC-TESTNET, and send test USDC to the scaAddress returned in the response. You need a Gateway deposit as well — run:

circle gateway deposit \
  --address <scaAddress> \
  --chain ARC-TESTNET \
  --amount 10

2. Construct your agent identifier Your agent’s x402 identifier is formed as:

8004:5042002:<tokenId>

Pass this as the X-Agent-ID header on every /api/x402/pay call. 3. Verify registration on-chain Open the explorerUrl from the response on ArcScan to confirm the registration transaction succeeded.

Each deployment creates new Circle wallets and a new on-chain identity. Deploying the same logical agent twice produces two distinct tokenId values with separate wallets and reputations. Store the tokenId and scaAddress securely after the first deployment.

Overview

Payments

Escrow

Streaming

x402

Agents

Deploy ERC-8004 Autonomous Agent — POST /api/agent/deploy

Request

Headers

Body Parameters

Response

200 — Success

500 — Server Error

408 — Timeout

Examples

Success Response

Next Steps After Deployment

​Request

​Headers

​Body Parameters

​Response

​200 — Success

​500 — Server Error

​408 — Timeout

​Examples

​Success Response

​Next Steps After Deployment

Request

Headers

Body Parameters

Response

200 — Success

500 — Server Error

408 — Timeout

Examples

Success Response

Next Steps After Deployment