Wallets
Retrieve and manage wallets. A wallet holds an account's funds at Frame's custodial provider, and every account is born with one. List your accounts' wallets, read one by id, follow its status from pending to active, and rename or tag it. Balances come from Frame's ledger, never the custodial balance.
export FRAME_API_KEY='sk_sandbox_...'
The Wallet object
Attributes
Unique identifier for the wallet.
Object type identifier. Always wallet.
The account that owns the wallet.
true for the one wallet the account addresses by default. A wallet becomes the default when it turns active, if its account has no default yet; mark another active wallet with PATCH /v2/wallets/{id}. A default the provider closes stays the default until you mark another.
A label you control, unique per account without regard to case. Every account is born with one wallet named Default.
Where the wallet is in its life. pending until Frame submits the account to the wallet provider, provisioning while the provider reviews it, active once money can reach it, rejected when the provider declines (terminal), closed once the account leaves the program. Closed wallets are hidden from lists.
Why the wallet is rejected, and null for any other status. unsupported_region: the wallet provider does not serve where the account is. unsupported_account_type: the provider does not open this kind of account. verification_declined: the provider declined the account's verification. Map it to your own message for the account holder.
What the account may spend from the wallet, from Frame's ledger rather than the custodial balance: platform fees still owed are already held back.
Money that has settled for the account but has not landed in the wallet yet: settled payments the next daily funding will move, and fundings still on their way. When a funding lands, its amount moves from incoming to available.
available plus incoming: everything the account has been paid that is in the wallet or on its way to it. Show this as the account holder's balance.
A set of key-value pairs you can attach to the wallet for your own reference.
true if live mode, false if test mode
Unix timestamp of when the wallet was created.
Unix timestamp of the last update.
{
"id": "g8h9i0j1-5678-9012-efab-3c4d5e6f7a8b",
"object": "wallet",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"default": true,
"name": "Default",
"status": "active",
"rejected_reason": null,
"available": {
"value": 120400,
"currency": "USD"
},
"incoming": {
"value": 2816,
"currency": "USD"
},
"balance": {
"value": 123216,
"currency": "USD"
},
"metadata": {},
"livemode": false,
"created": 1721010605,
"updated": 1721010605
}
List wallets
Returns a paginated list of the wallets on your platform: your own account's wallet and one per account you have created, newest first. Filter by account_id to see one account's wallets. Closed wallets are omitted; read one by id if you still hold its identifier. available is Frame's ledger view of what each account may spend, with platform fees still owed already held back.
Query parameters
Page number for pagination. Defaults to 1.
Number of results per page. Defaults to 10, maximum 100.
Only the wallets of this account.
Header parameters
The ID of one of your sub-merchants of record to act as. The request then reads and updates that account's wallets and its own accounts' wallets instead of yours, and an Idempotency-Key is scoped to it. An ID that is not one of your sub-merchants of record answers 404, and a sub-merchant of record that is not active answers 403 with code account_not_active. Omit it to act as your own account. Secret API keys only; a checkout session answers 403.
Returns
A paginated list of wallets.
curl --request GET \
--url https://api.framepayments.com/v2/wallets \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v2/wallets?account_id=00000000-0000-4000-8000-000000000001",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "00000000-0000-4000-8000-000000000002",
"name": "Default",
"status": "active",
"rejected_reason": null,
"metadata": {},
"object": "wallet",
"account_id": "00000000-0000-4000-8000-000000000001",
"default": false,
"available": {
"value": 0,
"currency": "USD"
},
"incoming": {
"value": 0,
"currency": "USD"
},
"balance": {
"value": 0,
"currency": "USD"
},
"livemode": false,
"created": 1745107200,
"updated": 1745107200
}
]
}
Get default wallet
Retrieves the default wallet of an account: the one wallet it addresses without an id. Name the account with account_id, or omit it for your own platform account, or under Frame-Account for that sub-merchant of record. An account with no default, or one that belongs to another platform, answers 404.
Query parameters
The account whose default wallet to read. Defaults to your own platform account, or under Frame-Account to that sub-merchant of record.
Header parameters
The ID of one of your sub-merchants of record to act as. The request then reads and updates that account's wallets and its own accounts' wallets instead of yours, and an Idempotency-Key is scoped to it. An ID that is not one of your sub-merchants of record answers 404, and a sub-merchant of record that is not active answers 403 with code account_not_active. Omit it to act as your own account. Secret API keys only; a checkout session answers 403.
Returns
Returns the default wallet object.
curl --request GET \
--url https://api.framepayments.com/v2/wallets/default \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Default",
"status": "active",
"rejected_reason": null,
"metadata": {},
"object": "wallet",
"account_id": "00000000-0000-4000-8000-000000000002",
"default": true,
"available": {
"value": 0,
"currency": "USD"
},
"incoming": {
"value": 0,
"currency": "USD"
},
"balance": {
"value": 0,
"currency": "USD"
},
"livemode": false,
"created": 1745107200,
"updated": 1745107200
}
Get wallet
Retrieves one wallet by ID, including its current status and available balance. A closed wallet still reads by id even though lists omit it. A wallet that belongs to another platform answers 404.
Path parameters
Wallet ID
Header parameters
The ID of one of your sub-merchants of record to act as. The request then reads and updates that account's wallets and its own accounts' wallets instead of yours, and an Idempotency-Key is scoped to it. An ID that is not one of your sub-merchants of record answers 404, and a sub-merchant of record that is not active answers 403 with code account_not_active. Omit it to act as your own account. Secret API keys only; a checkout session answers 403.
Returns
Returns the wallet object.
curl --request GET \
--url https://api.framepayments.com/v2/wallets/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Default",
"status": "active",
"rejected_reason": null,
"metadata": {},
"object": "wallet",
"account_id": "00000000-0000-4000-8000-000000000002",
"default": false,
"available": {
"value": 0,
"currency": "USD"
},
"incoming": {
"value": 0,
"currency": "USD"
},
"balance": {
"value": 0,
"currency": "USD"
},
"livemode": false,
"created": 1745107200,
"updated": 1745107200
}
Update wallet
Renames a wallet, replaces its metadata, or makes it the default of its account. Names are unique per account without regard to case, so a name another wallet on the same account already uses answers 422. metadata is replaced as a whole, not merged. default: true moves the default to this wallet; only an active wallet can become the default, and default: false answers 422, since the default moves only by marking another wallet. The request must carry an Idempotency-Key header: repeating a key with the same body replays the original response with Idempotent-Replay: true, and repeating it with a different body or against a different wallet answers 400.
Path parameters
Wallet ID
Header parameters
The ID of one of your sub-merchants of record to act as. The request then reads and updates that account's wallets and its own accounts' wallets instead of yours, and an Idempotency-Key is scoped to it. An ID that is not one of your sub-merchants of record answers 404, and a sub-merchant of record that is not active answers 403 with code account_not_active. Omit it to act as your own account. Secret API keys only; a checkout session answers 403.
A unique key for this write, at most 255 characters. Reuse it to replay the same response safely.
Body parameters
The new label. Unique per account without regard to case.
true makes this wallet the default of its account; the wallet must be active. false is refused.
A set of key-value pairs to attach to the wallet for your own reference. Replaces the stored metadata.
Returns
Returns the updated wallet object.
curl --request PATCH \
--url https://api.framepayments.com/v2/wallets/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY' \
--header 'Idempotency-Key: <value>'
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Payouts",
"object": "wallet",
"status": "active",
"balance": {
"value": 0,
"currency": "USD"
},
"created": 1745107200,
"default": false,
"updated": 1745107200,
"incoming": {
"value": 0,
"currency": "USD"
},
"livemode": false,
"metadata": {
"creator_id": "c_123"
},
"available": {
"value": 0,
"currency": "USD"
},
"account_id": "00000000-0000-4000-8000-000000000002",
"rejected_reason": null
}