Skip to main content
Meterlane handles two distinct types of credentials — management API keys and agent wallet private keys — plus USDC wallets managed through Circle’s MPC system. Understanding how each component works and where the risks lie helps you ship payment infrastructure safely. Follow the practices below before you go to production.

​
Agent private keys

Your x402 agent client signs payment headers using an ECDSA private key. This key authorises real USDC transfers on Base mainnet, so it must be treated with the same discipline as a production database password.
Never commit your agent private key (AGENT_PRIVATE_KEY) to source code or include it in a Docker image, config file, or client-side bundle. A leaked mainnet key can result in immediate and irreversible loss of funds.
Follow these rules for every environment where an agent runs:
  • Use a dedicated hot wallet. Create a fresh wallet address specifically for your agent. Fund it with only the USDC your agent needs to operate over a short period — not your entire treasury balance.
  • Load from the environment. Read AGENT_PRIVATE_KEY from an environment variable at runtime. Never hard-code or interpolate it into application source files.
  • Use a secrets manager in production. On cloud deployments, store the private key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Cloudflare Secrets, and so on) and inject it into the process at startup. Avoid storing it in plain-text .env files on production servers.
  • Separate sandbox and mainnet keys. Use a different wallet address and private key for Base Sepolia (sandbox) than for Base mainnet (production). This makes it impossible for a mis-configured environment variable to spend real funds.
# Load in your shell for local dev only
export AGENT_PRIVATE_KEY="0xabc123..."

# In production, inject from your secrets manager — never store in .env

​
Management API keys

Management API keys (bp_live_…) authenticate your calls to the Meterlane management API. They are org-scoped and can create routes, trigger payouts, and access payment history.
Revoke an API key immediately if you suspect it has been exposed. Go to Settings → API Keys in the dashboard and click Revoke next to the affected key. Revocation takes effect immediately.
  • Never expose API keys in client-side code. A bp_live_… key embedded in a browser application or mobile app is publicly visible to anyone who inspects network traffic or bundle contents.
  • Rotate keys on personnel changes. When a team member with access to an API key leaves your org, revoke the old key and issue a fresh one.
  • Name keys by purpose. Give each key a descriptive label (for example, prod-worker or ci-deploy) so you can identify and revoke individual keys quickly if needed.
  • Do not log the full key. Only the first 16-character prefix of an API key is safe to include in log output. Meterlane itself follows this rule — only the prefix and a SHA-256 hash are stored.

​
Sandbox before production

Always validate your integration in the sandbox environment before connecting to Base mainnet.
EnvironmentNetworkUSDC
SandboxBase Sepolia (eip155:84532)Test USDC only — no real value
ProductionBase mainnet (eip155:8453)Real USDC
The public x402 facilitator at x402.org works on Base Sepolia. Base mainnet requires a mainnet-capable facilitator. During your 14-day trial, all gateway and corridor operations run in sandbox mode by default.
Run your full end-to-end integration — including error cases and replayed payment headers — against Base Sepolia before you promote to mainnet. Mistakes with test USDC cost nothing; mistakes with real USDC may be irreversible.

​
Circle MPC wallets

When you use the Stablecoin Corridor, payouts are funded from Circle MPC wallets provisioned for your org. MPC (multi-party computation) means the wallet’s private key is never held in a single location — not in the Meterlane dashboard, not on your device, and not as a raw secret you need to manage.
  • No raw private keys in the dashboard. You will never see or handle a private key for your Circle MPC wallet. Key material is derived by Circle’s MPC system using your org’s entitySecret, which is registered with Circle once during onboarding.
  • The entitySecret stays in your environment. If you set up a self-hosted corridor integration, store CIRCLE_ENTITY_SECRET as a secure environment variable. It must never appear in logs, API responses, or source code.
  • Rotate if compromised. If you suspect your entitySecret has been exposed, generate a new one and re-register it with Circle immediately. Contact enterprise@meterlane.app if you need guidance during an incident.

​
Custom facilitator URLs

If you configure a custom facilitator URL in Settings → Developer, apply these checks:
Only use facilitator URLs from providers you fully trust. A malicious facilitator can manipulate payment verification and direct funds incorrectly.
  • Ensure the URL uses HTTPS. Plain HTTP facilitator endpoints are not acceptable for any environment where real USDC is at stake.
  • Verify the domain belongs to a provider you have evaluated. Do not copy facilitator URLs from untrusted sources.
  • Test the custom facilitator end-to-end in the sandbox before enabling it on production routes.

​
Nonce replay protection

The Meterlane gateway automatically rejects replayed x402 payment headers. Each payment nonce is tracked for a short window after it is used. If a client attempts to reuse the same signed payment header within that window, the gateway returns a 402 rejection rather than processing a duplicate payment. This protection is active by default on all routes — you do not need to configure anything. However, make sure your agent client generates a fresh nonce for every payment request rather than caching or reusing previous payment headers.

​
Security checklist

  • Agent private key loaded from environment variable, not hard-coded
  • Dedicated hot wallet for the agent with limited USDC balance
  • Separate wallet addresses for sandbox and mainnet
  • Management API key stored in secrets manager, not in source code
  • Custom facilitator URL (if used) is HTTPS and from a trusted provider
  • Full integration tested on Base Sepolia before mainnet promotion
  • Team members granted least-privilege roles (org:member where admin is not needed)
  • API key names indicate purpose so individual keys can be rotated quickly