Crypto top-up API for AI agents: fund tools and compute

An agent can find the right tool, prepare a request and still stop at a familiar obstacle: its balance is empty, and someone has to open a checkout page.

A crypto top-up API gives the agent another way to fund its work. It requests a credit purchase, receives payment instructions, pays through its own authorized wallet and waits for the credits to arrive. Those credits can then fund supported AI models, tools and GPU compute in one Dreamtune workspace.

This guide explains the Dreamtune agent top-up interface and the integration pattern. Use SDK version 0.1.2 or the hosted MCP tools. Wallet signing stays with your separately authorized wallet. The existing browser crypto checkout is also available in Billing.

What the top-up API does

The API creates a purchase of USD-denominated Dreamtune credits. Its payment instructions specify the crypto asset, exact network, deposit address, amount, expiry and any required memo. Your wallet handles signing and broadcasting the transfer. Dreamtune never needs the wallet's seed phrase or private key.

The flow has five steps:

1. Read the workspace balance and available crypto payment options.
2. Choose an enabled asset and network, then check its current minimum.
3. Create a top-up using a saved idempotency key.
4. Have the agent's wallet transfer the quoted amount on the specified network before the quote expires.
5. Check the saved top-up until its state is credited, then continue the task.

A payment request is not spendable credit. Network detection, confirmation and gateway settlement happen before Dreamtune credits the workspace. A transaction hash supplied by the client does not establish that the purchase was paid.

Create a payment request through the API

Create a key in API keys with billing access. The key needs billing:read to read balances, options and saved top-ups, and billing:topup to create or check a payment. Existing keys do not gain these permissions automatically. Tool, model and compute permissions remain separate.

First inspect GET /v1/developer/billing/crypto/options. Select a code from the returned assets and check GET /v1/developer/billing/crypto/options?currency=<code>. The response includes its current minimum and the configured top-up fee. Limits use USD cents; the requested purchase amount uses a decimal USD string.

Create the purchase with POST /v1/developer/billing/crypto/top-ups. The following server-side example uses environment variables for the API origin, secret and selected payment currency:

curl --request POST "$DREAMTUNE_API_ORIGIN/v1/developer/billing/crypto/top-ups" \
  --header "Authorization: Bearer $DREAMTUNE_API_KEY" \
  --header "Idempotency-Key: $TOP_UP_INTENT" \
  --header "Content-Type: application/json" \
  --data "{\"amount\":\"10.00\",\"payCurrency\":\"$PAY_CURRENCY\"}"

Save TOP_UP_INTENT before making the request. Reuse it only for identical purchase parameters. If a request times out, look up the saved top-up or repeat the identical request with that same key. A new key creates a different purchase intent.

Only transfer when instructionsState is ready and the returned paymentInstructions.expiresAt is still in the future. Verify payCurrency, network, address, amount, memo and, for tokens, the token identity against your wallet policy. Never substitute a similarly named asset on another chain. Keep the amount as a decimal string until the wallet converts it into that asset's atomic units.

Read the saved record with GET /v1/developer/billing/crypto/top-ups/:id. Use POST /v1/developer/billing/crypto/top-ups/:id/check without a body to refresh gateway status. A top-up in needs_reconciliation, or with uncertain payment instructions, needs investigation before another transfer. It is not a signal to pay twice.

Connect the same workflow through MCP

The release adds five tools to Dreamtune MCP:

• wallet_balance reads available workspace credit in USD micro-units.
• crypto_top_up_options discovers payment assets, networks and limits.
• create_crypto_top_up creates the credit purchase and payment instructions.
• get_crypto_top_up reads a saved purchase.
• check_crypto_top_up refreshes payment status and applies verified credit once.

These tools prepare and track a purchase. A separate wallet integration signs the transfer. That separation lets you connect the payment workflow to the wallet your agent already uses and enforce its existing transfer policy.

After rollout, follow the Dreamtune MCP connection guide. An MCP connection does not itself provide a funded crypto wallet or permission to move its funds.

Set a funding policy before giving an agent a wallet

Choose a replenishment threshold, maximum purchase and daily funding budget in the wallet integration. Allowlist the intended payment service, token contracts and networks. Apply those rules in executable wallet policy; a prompt alone does not enforce a transfer limit.

For a first integration, require approval for the initial payment and observe the full lifecycle. Once the top-up reaches credited, confirm the balance, run a small authorized task and inspect its charge in Logs. Use Runs to review activity.

The top-up API does not automatically retry transfers, refresh an expired quote or withdraw Dreamtune credits. Each new purchase gets a new intent and verified instructions. Partial payments, repeated deposits and wrong-asset transfers may require support review.

What you pay and what becomes credit

The requested USD amount is the credit purchase. Dreamtune's configured top-up fee is added to the payment price and saved with the purchase. Payment-provider charges and the sending wallet's network fees are separate. They do not increase the purchased credit.

The gateway determines the crypto amount and payment window. Read the actual response before sending funds: a minimum can change with the asset, settlement pair and network conditions. Do not assume a small USD purchase is available on every chain.

Where this fits in the agent ecosystem

Wallet-enabled agents can use this pattern to purchase resources for research, content generation or compute jobs. An integration is most useful when it demonstrates the complete task: fund credits, verify settlement, call a permitted service and report the result and charge.

Coinbase AgentKit provides wallet and action-provider building blocks. Its contribution guide describes how external contributors can propose integrations. Dreamtune is not claiming an accepted AgentKit integration or partnership.

x402 is another route for agents to pay for API access. The prepaid top-up workflow described here uses NOWPayments invoices and payment-status verification; x402 support would be a separate integration.

For a developer evaluating the release, begin with payment-option discovery and a saved top-up record. Complete a controlled funded test before allowing unattended replenishment. The useful result is an agent that can finish its task with a funding history you can inspect.

Sources and implementation references

• NOWPayments API documentation: Create payment by invoice and Get payment status.
• NOWPayments endpoint descriptions.
• NOWPayments minimum payment guidance.
• Dreamtune catalog for supported services and published rates.

Provider documentation checked October 18, 2026. Asset availability and payment amounts come from the current API response.