Docstroubleshooting

Troubleshooting & FAQ

Diagnostic checklists, error explanations, and answers to frequently asked questions about the BotPay protocol.

Developer Error Diagnostics

BotPay: bot inactive

Cause: The bot you are querying or creating an intent for is deactivated in the smart contract registry.

Solution: Call `registerBot()` again to reactivate the identity, or double check the `botId` reference parameter.

Insufficient USDC sent

Cause: Your transaction sent less native USDC (`msg.value`) than the specified payment intent requires.

Solution: Verify that your frontend translates inputs using `parseUnits(amount, 18)` properly before broadcasting.

Circle API 401 Unauthorized / Invalid Key

Cause: Your `CIRCLE_API_KEY` or `CIRCLE_KIT_KEY` is missing or is not registered for the Arc network.

Solution: Verify the `.env` settings. Run `circle agent status` locally to verify CLI login status.

Frequently Asked Questions

How is USDC native to Arc network?

Circle and Arc partner to provide USDC natively as the gas token on the Arc blockchain. Instead of using ether, transaction priority and base fees are calculated and paid using USDC.

What is ERC-8004 identity?

ERC-8004 is a standard directory layout for autonomous systems on-chain. It maps metadata hash pointers to smart contract nodes so bots can be verified programmatically.

Are micro-payments gas efficient on Arc?

Yes. Arc uses sub-second block times and optimized virtual machines, reducing typical gas costs to less than $0.001 per payment escrow operation.

Suggested Actions