Environment Setup

​

Environments at a glance

export SOHOPAY_API_KEY="sk_test_..."
export SOHOPAY_BASE_URL="https://api-sandbox.sohopay.xyz/v1"

export SOHOPAY_API_KEY="sk_live_..."
export SOHOPAY_BASE_URL="https://api.sohopay.xyz/v1"

​

Base RPC configuration

import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const client = createPublicClient({
  chain: baseSepolia, // chain ID 84532
  transport: http("https://sepolia.base.org"),
});

const receipt = await client.getTransactionReceipt({
  hash: "0x4d5e...9a0b", // settlement_tx from a payment
});

​

Test USDC faucet

1. Go to faucet.circle.com.
2. Select Base Sepolia as the network.
3. Paste your wallet address and request USDC.

​

API key storage

• Environment variables — the minimum bar. Load from .env locally and keep .env in .gitignore. Never hardcode a key in source.
• Secrets managers — for anything deployed: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, Doppler, or 1Password for teams. Inject at runtime; don’t bake keys into container images.
• One key per service — give each deployed service its own key so you can rotate or revoke one without touching the others.
• Separate sandbox and mainnet configs — keep them in different secret scopes so a staging deploy can never pick up a sk_live_ key.

​

Network troubleshooting

• 401 INVALID_API_KEY on a key that works elsewhere — you’re crossing environments: a sk_test_ key against api.sohopay.xyz (or vice versa). Check the base URL first.
• DNS or TLS failures — corporate proxies sometimes block .xyz domains. Confirm with curl -v https://api-sandbox.sohopay.xyz/v1/health and allowlist both API hosts in your egress rules.
• 429 RATE_LIMITED — back off for the number of seconds in the Retry-After header. Per-agent limits are enforced by the Policy Service; see Rate Limits.
• Timeouts on public RPC — sepolia.base.org throttles aggressively. Retry with backoff or switch to a dedicated provider.
• Payments stuck in pending — the MPC design is fail-closed: if the Policy Service is unavailable, no settlements occur. Check API health and the maintenance window (Sun 02:00–02:30 UTC) before debugging your own code. See SLA.

​

Next steps