---
title: "Create or fund a Grove tipping account using x402 payments"
method: POST
path: "/v1/fund"
tags: ["funding"]
---

# Create or fund a Grove tipping account using x402 payments

`POST /v1/fund`

Fund a Grove tipping account using x402 payments.

Behavior:

1. New account flow (no `Authorization`):
  1. Call without `PAYMENT-SIGNATURE` to receive HTTP 402 with x402 payment requirements.
  2. Sign the payment using the provided requirements.
  3. Call again with `PAYMENT-SIGNATURE` set to the signed payload.
  4. On success, a custodial wallet and Grove account are created and funded, and an `api_key` JWT is returned.

2. Existing account flow (with `Authorization`):
  1. Call with a valid `Authorization: Bearer <api_key>` header and no `PAYMENT-SIGNATURE` to receive HTTP 402.
  2. Sign the payment and call again with both `Authorization` and `PAYMENT-SIGNATURE`.
  3. On success, the existing account balance is increased.

In both flows, the endpoint:

- Verifies the x402 payment locally.
- Settles the payment using the configured facilitator.
- Waits for the provider-reported balance to reflect the funded amount.
- Returns the funded amount, new balance, and settlement transaction hash.

The `FundResponse` payload:

- For new accounts: includes `funded_amount`, `new_balance`, `tx_hash`, `account_id`, and `api_key`.
- For existing accounts: includes `funded_amount`, `new_balance`, and `tx_hash`.

Multi-network support:
- Specify `network` and `token` query params to fund with specific asset
- Defaults to DEFAULT_NETWORK and DEFAULT_TOKEN if not specified
- Account.network is set on first funding (immutable - represents VM type)
- Multi-network balances tracked in AccountBalance table

## Query parameters

- `amount` string — Amount to credit to the tipping account. Unit: human-readable amount (not atomic units), for example `"0.10"`, `"1"`, `"5.25"`. Purpose: this balance is used by an agent or human to tip content creators (agents or humans) on the internet. Flow: - Without `Authorization`: creates a new Grove account, funds it, and returns an `api_key` JWT. - With `Authorization`: funds the existing Grove account associated with that JWT. Constraints: - Must be a positive number. - Precision must not exceed the configured decimals for the token.
- `network` string, nullable — Network identifier (e.g., "base", "base-sepolia"). Supported networks: ethereum-mainnet, base, base-sepolia, solana-mainnet, solana-devnet. Defaults to: base Note: The account's primary network (Account.network) is set on first funding and represents the Virtual Machine (EVM, SVM, etc.). Multi-network balances are tracked separately in the AccountBalance table.
- `token` string, nullable — Token symbol (e.g., "USDC", "ETH"). Defaults to: USDC Supported tokens vary by network. Check the network's token configuration for available options.
- `referral_code` string, nullable — Optional referral code from an existing Grove user (e.g., "GRV-ABC123"). Only applies to new account creation (when no `Authorization` header is provided). If the referral code is valid, the new account will be linked to the referrer. If invalid (not found or self-referral), account creation still succeeds but `referral_status.applied` will be `false` in the response. The new account's own referral code is returned in `referral_code` field so they can share it with others.

## Headers

- `authorization` string, nullable — Optional Bearer JWT issued by Grove that identifies an existing tipping account. Format: `Authorization: Bearer <api_key>`. When absent: - A new server wallet and Grove account are created after successful payment. - A new `api_key` is returned and should be used as the Bearer token in future calls. When present: - The call is treated as a top-up for the existing account. - The response includes the new balance but does not issue a new `api_key`.
- `PAYMENT-SIGNATURE` string, nullable — Base64-encoded x402 payment payload. This header participates in a two-step x402 funding flow: 1. First request: - Call `/v1/fund` without payment header (and optionally with `Authorization`). - The API responds with HTTP 402 and an `accepts` array describing the required payment. 2. Second request: - Sign the x402 payment off-platform using the details from the 402 response. - Call `/v1/fund` again with the `PAYMENT-SIGNATURE` header set to the signed payload. - On success, the payment is verified and settled, and the account is created or funded.

## Response `200`

Successful Response

- FundResponse — Response model for successful funding. When creating a new account (no JWT provided): - account_id, api_key, tipping_address, and earning_address are populated - Use api_key as Bearer token for future requests - referral_code contains the new account's shareable referral code - referral_status contains feedback on any provided referral code When funding existing account (JWT provided): - account_id and api_key are None - tipping_address and earning_address are populated - referral_code and referral_status are None (referrals only apply to new accounts)
  - `funded_amount` string, required
  - `new_balance` string, required
  - `tx_hash` string, required
  - `account_id` string, nullable
  - `api_key` string, nullable
  - `tipping_address` string, nullable
  - `earning_address` string, nullable
  - `eoa_owner_address` string, nullable
  - `smart_account_address` string, nullable — ERC-4337 Smart Account address (the earning wallet)
  - `referral_code` string, nullable
  - `referral_status` ReferralStatus — Status of referral code application during account creation. Included in FundResponse to provide feedback on referral code processing. Allows successful account creation even with invalid referral codes, while still informing the user of the outcome.
    - `applied` boolean, required
    - `message` string, nullable
  - `address` string, nullable, required
  - `client_address` string, nullable, required
  - `earnings_wallet` EarningsWallet, required — Dual earnings-wallet representation (owner EOA + Smart Account).
    - `eoa_address` string, nullable — Owner EOA address (non-earning key)
    - `smart_account_address` string, nullable — Smart Account address used as canonical earning wallet
    - `earnings_address` string, nullable, required — Canonical earnings address for sender-path use.
  - `earnings_address` string, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/revisions/f286b48a8105/schema)