Balance refill endpoints require a signed-in user session. Start with
Authentication and Funding & Withdrawals.
$100 minimum and a $50 refill amount on Polygon. After a completed
trade:
The requested delivery is the larger of the configured refill amount or the amount needed to
restore the minimum. Network and bridge fees are paid from the source balance and must stay within
the user’s configured maximum fee.
When a refill runs
A refill is considered only after a trade has finished and all orders linked to that trade are in a terminal state, such as filled, canceled, expired, or failed. AGG refreshes the balance after the trade before comparing it with the policy minimum.Creating a policy or making a withdrawal does not immediately trigger a refill. An open resting
limit order does not trigger one either.
- If another trade is active or queued, AGG waits until queued trading is finished before considering the refill.
- Once a refill has started, a newly submitted trade waits for the refill to finish.
- AGG runs at most one balance-moving operation for a user at a time.
Create a policy
Amounts use six-decimal USDC integer strings. For example,"100000000" is $100 and
"50000000" is $50.
$250 per UTC day and $2 in fees per refill. Pass
dailyCapRaw or maxFeeRaw when the user wants different limits. The daily cap is applied
conservatively to each requested delivery plus its maximum allowed fee and must be large enough to
cover the configured amounts and fee limit. See the
Create balance refill policy API
for field constraints and the complete request and response schemas.
Read, update, or pause a policy
Use the SDK methods to build the policy controls in your app:lastObservedRaw, lastEvaluatedAt,
nextEligibleAt, and latestAttempt so your app can show its current state without reproducing the
refill logic.
List policies
Read the user’s configured policies and latest attempt.
Update or pause a policy
Change limits or switch a policy between enabled and paused.
Monitor refill attempts
Fetch the most recent attempts when you need a detailed activity view:reserved and executing, then ends as completed or failed. Use
completedAmountRaw, feeRaw, and errorMessage to present the final outcome. The endpoint returns
the 25 most recent attempts for the policy.
List refill attempts
View the complete attempt response schema and status fields.
Source balances and fees
AGG selects an available managed USDC balance on a different supported chain. The source must have enough spendable USDC for the requested delivery and the maximum fee; funds already reserved for orders or other operations are not available to a refill. Managed balance refills do not pull money from a bank account, card, or external wallet. If no eligible managed source balance is available, or if the fee or daily cap would be exceeded, no transfer starts. The policy remains enabled and can be considered again after a later completed trade.Withdrawals
Withdrawals and balance refills are serialized so they cannot spend the same managed balance:- If a withdrawal is already in progress, AGG does not start a refill.
- If a refill is already in progress, a withdrawal request returns
409. Retry it shortly. - A withdrawal can take the target balance below its minimum, but the withdrawal itself does not trigger a refill. The next eligible completed trade can trigger a new evaluation.
API reference
Create a policy
Configure a target chain, balance minimum, and refill amount, with optional custom safety limits.
List policies
Load all policies owned by the authenticated user.
Update a policy
Change thresholds or pause and resume automatic refills.
List attempts
Review recent refill activity and outcomes.