> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fund Goal

> Top up the budget of a recurring compute goal

## Overview

Tops up the budget of a **recurring** compute goal so it can keep running on its
schedule. The requested `amount` (USDC) is added to both the goal's total and
remaining budget. One-off goals cannot be funded — fund a recurring goal or
create a new goal instead.

This is a **paid endpoint** that uses the x402 quote-then-pay flow, exactly like
[creating a goal](/api-reference/compute/create): the top-up `amount` IS the price.

1. Call once with `{ amount }` and no payment → you get a **402** with a
   `payment_request` and a `context.quote_id`.
2. Sign the USDC payment authorization and call again with the
   `X-Quote-Id` header and the payment signature → the budget is credited and you
   get a **200**.

The OneShot SDK does both steps for you:

```typescript theme={null}
const result = await agent.fundComputeGoal('goal_01HX...', 10.00);
console.log(`New total: $${result.total_budget}`);
```

## Authentication

Send your agent wallet address in the `X-Agent-ID` header. Only the wallet that
created the goal can fund it; other callers get a `404`. The wallet that pays must
be the goal owner — payment from any other wallet is rejected when the quote is
redeemed.

## Path Parameters

<ParamField path="goalId" type="string" required>
  The goal ID to top up
</ParamField>

## Request Body

<ParamField body="amount" type="number" required>
  Amount to add to the goal's budget, in USDC. Must be a positive number.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response

<ResponseField name="data.goal_id" type="string">The funded goal ID</ResponseField>
<ResponseField name="data.topped_up" type="number">Amount added to the budget (USDC)</ResponseField>
<ResponseField name="data.total_budget" type="string">New total budget after the top-up (USDC)</ResponseField>
<ResponseField name="data.remaining" type="string">New remaining budget after the top-up (USDC)</ResponseField>

<RequestExample>
  ```bash Step 1 — get quote (402) theme={null}
  curl -X POST https://win.oneshotagent.com/v1/compute/goal_01HX8K3YZ/fund \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -d '{ "amount": 5.00 }'
  ```

  ```bash Step 2 — pay (200) theme={null}
  curl -X POST https://win.oneshotagent.com/v1/compute/goal_01HX8K3YZ/fund \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -H "X-Quote-Id: quote_01HX..." \
    -H "Payment-Signature: <base64 x402 payment>" \
    -d '{ "amount": 5.00 }'
  ```
</RequestExample>

<ResponseExample>
  ```json 402 (first call) theme={null}
  {
    "error": "payment_required",
    "message": "Payment required to fund compute goal.",
    "payment_request": {
      "chain_id": 8453,
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "5.000000",
      "recipient": "0xMerchantWallet..."
    },
    "context": {
      "tool": "compute_fund",
      "quote_id": "quote_01HX...",
      "goal_id": "goal_01HX8K3YZ...",
      "topped_up": "5.000000",
      "total_budget": "5.000000",
      "expires_at": "2026-06-04T09:05:00.000Z"
    }
  }
  ```

  ```json 200 (after payment) theme={null}
  {
    "success": true,
    "data": {
      "goal_id": "goal_01HX8K3YZ...",
      "topped_up": 5,
      "total_budget": "15.000000",
      "remaining": "8.350000"
    }
  }
  ```
</ResponseExample>

<Warning>Only recurring goals can be funded (`not_recurring` error otherwise), and the goal must have an existing budget record (`no_budget` error otherwise).</Warning>