Sign in

v1

latestOpenAPI 3.1.02026-07-13143194365.4 KB
funding

Create or fund a Grove tipping account using x402 payments

Fund a Grove tipping account using x402 payments.

Behavior:

  1. New account flow (no Authorization):

  2. Call without PAYMENT-SIGNATURE to receive HTTP 402 with x402 payment requirements.

  3. Sign the payment using the provided requirements.

  4. Call again with PAYMENT-SIGNATURE set to the signed payload.

  5. On success, a custodial wallet and Grove account are created and funded, and an api_key JWT is returned.

  6. Existing account flow (with Authorization):

  7. Call with a valid Authorization: Bearer <api_key> header and no PAYMENT-SIGNATURE to receive HTTP 402.

  8. Sign the payment and call again with both Authorization and PAYMENT-SIGNATURE.

  9. 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
post/v1/fund

Query parameters

amountstring
    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.
    

    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.
networkstring 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.
    

    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.
tokenstring nullable
    Token symbol (e.g., "USDC", "ETH").

    Defaults to: USDC

    Supported tokens vary by network. Check the network's token configuration for available options.
    

    Token symbol (e.g., "USDC", "ETH").

    Defaults to: USDC

    Supported tokens vary by network. Check the network's token configuration for available options.
referral_codestring 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.
    

    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

authorizationstring 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`.
    

    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-SIGNATUREstring 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.
    

    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

Successful Response

funded_amountstring required
new_balancestring required
tx_hashstring required
account_idstring nullable
api_keystring nullable
tipping_addressstring nullable
earning_addressstring nullable
eoa_owner_addressstring nullable
smart_account_addressstring nullable

ERC-4337 Smart Account address (the earning wallet)

referral_codestring nullable
addressstring nullable required
client_addressstring nullable required
earnings_addressstring nullable required