Allowance
Allowance documentation for Compose Finance APIs and integrations.
The Allowance Module is a Safe smart-contract module on Base that sets organization-level USDC spending limits for API withdrawals. This is not an ERC-20 approve or token allowance.
Allowance applies to your organization's embedded Safe wallet, even though the read endpoint path is /customers/withdrawal/allowance (there is no customerId parameter).
How allowance fits with wallets
API withdrawals (POST /customers/{customerId}/withdrawal) move USDC from your embedded wallet through the per-bank withdrawal wallet off-ramp pipeline. The allowance module controls whether that API call executes immediately (PROCESSING) or becomes a manual proposal (PROPOSED) in the dashboard.
See Wallets for how deposit wallets, withdrawal wallets, and your embedded wallet route funds.
Prerequisites
| Step | Who | What |
|---|---|---|
| 1 | Org Owner (dashboard) | Enable API withdrawals for your organization |
| 2 | Org Owner (dashboard) | Configure on-chain allowance via Safe signing |
If step 1 is not complete, the dashboard shows a contact-support message and GET /withdrawal/allowance returns { "enabled": false, "allowance": null } with 200.
Dashboard setup
Enable API withdrawals
- Log in to the Compose dashboard as an Owner
- Go to Settings → API Withdrawals (
/settings/api-withdrawals) - Click Enable
- Set Allowance Amount (USDC) — maximum USDC withdrawable via API per reset period
- Set Reset Period:
- One-time (no reset) —
resetPeriodMinutes: 0 - Daily (24 hours) —
1440 - Weekly (7 days) —
10080 - Monthly (30 days) —
43200
- One-time (no reset) —
- Click Confirm with Passkey to sign the on-chain Safe transaction
- If your organization uses multisig, additional approvers may need to sign before the change takes effect
Update allowance — Manage → Update Allowance → adjust amount and reset period → confirm with passkey.
Disable — Manage → Disable → revokes the delegate and disables the module → confirm with passkey.
Security note: Withdrawals that exceed your allowance are created as PROPOSED and require approval in the Compose dashboard. Set appropriate limits, monitor usage regularly, and keep your API key secure.
Reading allowance via API
Use GET /api/v2/customers/withdrawal/allowance to check your current allowance before initiating withdrawals. See Get withdrawal allowance for the full API reference.
curl -X GET 'https://compose.finance/api/v2/customers/withdrawal/allowance' \
-H 'Authorization: Bearer YOUR_API_KEY'enabled | allowance | Meaning |
|---|---|---|
false | null | API withdrawals unavailable, embedded Safe wallet not configured, or module not enabled on-chain |
true | null | Module and delegate configured, but no spending limit set yet |
true | { limit, spent, available, ... } | Fully configured — check available before withdrawing |
enabled: true means the on-chain module and delegate are configured. Automatic withdrawals still require a non-null allowance with sufficient available balance.
Using allowance in withdrawals
When you call POST /customers/{customerId}/withdrawal:
- Automatic (
PROCESSING) — sufficient available allowance and sufficient USDC in your embedded Safe wallet - Manual (
PROPOSED) — withdrawal exceeds available allowance, insufficient embedded Safe wallet balance, or automatic execution fails
See Create customer withdrawal for the full API reference.