Skip to main content
The Wallet service manages multi-entity wallets for users, organizations, and projects. It is served by the Wallets microservice, configured via REACT_APP_WALLETS_API_BASE_URL (falls back to REACT_APP_ORGANIZATIONS_API_BASE_URL). All requests require Api-Key and Authorization: Bearer <token> headers.

​
List Wallets

GET /wallets
Return all wallets accessible to the authenticated user, across all entity types (personal, organization, project, agent). 
curl https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/wallets \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"
​
entity_type
string
Filter by entity type: user, organization, project.
​
data
array
Array of wallet objects.

​
Get Wallet

GET /wallets/{addressHash}
Fetch details for a specific wallet by its address hash. Results are cached for 5 minutes; append ?cache_bust=<timestamp> to force a fresh fetch.
​
addressHash
string
required
The wallet’s unique address hash.
curl https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/wallets/0xabc123 \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"

​
Create Entity Wallet

POST /wallets/create_entity_wallet
Create a new wallet for an organization, project, or other entity. Organization wallets are created automatically when a new organization is created.
​
entity_wallet.entity_type
string
required
The owning entity type: user, organization, or project.
​
entity_wallet.entity_id
string
required
The unique ID of the owning entity.
​
entity_wallet.entity_name
string
required
A human-readable name for the wallet owner.
​
entity_wallet.purpose
string
The wallet purpose. Common values: operating (organizations), project_funds (projects), general. Defaults to general.
​
entity_wallet.currency
string
The currency type. Defaults to CREDITS.
​
entity_wallet.metadata
object
Optional metadata. For project wallets, include { "organization_id": "<id>" }.
curl -X POST https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/wallets/create_entity_wallet \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_wallet": {
      "entity_type": "organization",
      "entity_id": "org-123",
      "entity_name": "Acme Corp",
      "purpose": "operating",
      "currency": "CREDITS"
    }
  }'

​
Update Wallet

PUT /wallets/{addressHash}
Update wallet properties such as entity_name and description.
​
addressHash
string
required
The wallet’s unique address hash.
​
wallet
object
required
Object containing the fields to update.

​
Transaction History

GET /wallets/{addressHash}/transactions
List transactions for a specific wallet with pagination.
​
addressHash
string
required
The wallet’s unique address hash.
​
page
integer
Page number. Defaults to 1.
​
per_page
integer
Items per page. Defaults to 20.
curl "https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/wallets/0xabc123/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"
​
data
array
Array of transaction objects.
​
meta.page
integer
Current page number.
​
meta.per_page
integer
Items per page.
​
meta.total_count
integer
Total number of transactions.

​
Transact (Universal Transfer / Conversion)

POST /wallets/transact
The universal transaction endpoint handles both transfers between wallets and asset conversions within a single wallet. When from_wallet and to_wallet are the same address, the operation is treated as a conversion.
​
transaction.from_wallet
string
required
Source wallet address hash.
​
transaction.to_wallet
string
required
Destination wallet address hash. Set equal to from_wallet for an in-wallet conversion.
​
transaction.from_asset
string
required
Asset type to debit from the source wallet (e.g., CREDITS).
​
transaction.to_asset
string
required
Asset type to credit to the destination wallet. Set equal to from_asset for a same-asset transfer.
​
transaction.amount
number
required
The amount to transfer or convert. Must be a number (not a string).
​
transaction.description
string
Human-readable description of the transaction.
​
transaction.metadata
object
Additional metadata.
# Transfer CREDITS between wallets
curl -X POST https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/wallets/transact \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "from_wallet": "0xabc123",
      "to_wallet": "0xdef456",
      "from_asset": "CREDITS",
      "to_asset": "CREDITS",
      "amount": 100,
      "description": "Transfer 100 CREDITS",
      "metadata": { "purpose": "wallet_transfer" }
    }
  }'

​
Debit Wallet

POST /wallets/{addressHash}/debits
Deduct funds from a wallet. Users can debit their own wallets.
​
addressHash
string
required
The wallet’s unique address hash.
​
debit.amount
number
required
The amount to debit.
​
debit.description
string
required
Human-readable description of the debit.
​
debit.reference_id
string
Optional external reference ID for idempotency.

​
Credit Wallet

POST /wallets/{addressHash}/credits
Add funds to a wallet. Requires admin-level access (Admin-Access header).
​
addressHash
string
required
The wallet’s unique address hash.
​
credit.amount
number
required
The amount to credit.
​
credit.description
string
required
Human-readable description of the credit.
​
credit.reference_id
string
Optional external reference ID.
This endpoint requires the Admin-Access header with a valid admin access token.

​
Wallet Transfers

Wallet transfers are a two-step process: the sender creates a transfer request, and the recipient accepts it. Both steps require verification codes.

​
List Transfer Requests

GET /wallet_transfers
​
page
integer
Page number. Defaults to 1.
​
per_page
integer
Items per page. Defaults to 20.

​
Create Transfer Request

POST /wallet_transfers
​
transfer
object
required
Transfer details object.

​
List Pending Transfers

GET /wallet_transfers/pending
Return transfers awaiting action by the authenticated user.

​
Verify Transfer Sender

POST /wallet_transfers/{transferId}/verify_sender
​
transferId
string
required
The transfer ID.
​
verification_code
string
required
The sender’s verification code.

​
Accept Transfer

POST /wallet_transfers/{transferId}/accept
​
transferId
string
required
The transfer ID.
​
verification_code
string
required
The recipient’s verification code.

​
Reject Transfer

POST /wallet_transfers/{transferId}/reject
​
transferId
string
required
The transfer ID.

Build docs developers (and LLMs) love

Get started for freeTalk to us