Credits

How Thirdfy credits work for people and agents. Free requests each day, how an agent checks its balance, and how to top up with USDC on Base.

Thirdfy charges credits for the actions it runs: trades, deposits, orders and paid data reads. Thirdfy checks the balance before an action runs. Your balance shows in USD; credits are the internal unit.

Free requests

Each account gets 20 free requests a day (the current limit). They reset at 00:00 UTC.

  • A free request is used only when the paid balance can't cover the action.
  • A failed action does not use one.
  • When they run out, actions return DAILY_FREE_LIMIT_EXCEEDED until you top up or the day resets.

Give this to your agent

Read https://docs.thirdfy.com/agents.md. Then check my Thirdfy credits:
tell me my balance, remind me how the free daily requests work,
and if I'm running low, give me the link to top up.

Your agent reads its balance and tells you when to top up. It does not buy credits with your money on its own.

How an agent checks its balance

SurfaceCallCredential
MCPgetCreditsBalanceThe agent key in the connection header
RESTGET https://api.thirdfy.com/api/v1/agent/credits/balancex-agent-api-key: agent-...
CLIthirdfy-agent credits balance --jsonThe owner session from login email

The agent endpoint returns availableUsd and balanceCredits for the agent's own ledger, and never another agent's.

Top up

Top up with USDC on Base at thirdfy.com/credits. Sign in with the same email you used for your agent.

OptionAmount
Presets$10, $25 or $50
CustomAny whole-dollar amount

On the credits page you can also redeem coupon codes and see purchases and usage.

Top up an agent's own balance with x402

An agent on agent_wallet spends from its own ledger. To add credits to that ledger directly, call the agent endpoint with the agent key and pay with x402 (USDC on Base):

# 1. Ask for the price: answers 402 Payment Required with the USDC amount
curl -s -X POST https://api.thirdfy.com/api/v1/agent/credits/buy-with-x402 \
  -H "Content-Type: application/json" \
  -H "x-agent-api-key: $THIRDFY_AGENT_API_KEY" \
  -d '{"sku":"topup_usd_10"}'

# 2. Retry with the signed x402 payment in the PAYMENT-SIGNATURE (or X-PAYMENT) header
  • Any wallet can pay with a signed x402 payment. The credits always go to the agent that owns the key, whatever the request body says.
  • A plain USDC transfer can be claimed with txHash only when it came from the agent's key, its execution wallet or its owner wallet.
  • One payment credits one ledger once. A second claim returns 409 PAYMENT_ALREADY_CLAIMED.
  • The reply has the same fields as the agent balance, plus the purchase.

This works for agents and apps that hold an x402-capable wallet. An agent that only has the Thirdfy MCP or CLI can't sign an x402 payment from its execution wallet yet, so it asks you to top up.

Apps that top up a person's account use POST /api/v1/credits/buy-with-x402 the same way.

Gas

Thirdfy sponsors network gas where it is configured for the chain and action, which covers most actions on Base and the main EVM chains. On DogeOS the execution wallet pays its own gas in DOGE. On Arc, gas is paid in USDC, Arc's native gas token, so the wallet needs only USDC. Credits pay for Thirdfy's work; gas sponsorship is separate.

Related

Vision
Why Thirdfy exists. Autonomous agents, governed execution, and the future of finance on delegated capital.
Execute Intents
Thirdfy validates and executes intents for registered agents. Any DeFi agent can be validated here.