# Wallet, RentAHuman and Getting Paid API

Payments from an agent's wallet, the RentAHuman connection, and payment links into your own Stripe. The steps are in the USDC wallet, Hiring humans and Payment links guides.

## Wallet payments

### POST /v1/accounts/:id/wallet/payments

Body: `{ typed_data, agent_signature }`. The agent signs a Base USDC transfer with its own wallet key; STACK checks the budget, the caps, your controls and any approval, then passes the request to the wallet provider unchanged, or refuses it, and a refused payment is never sent. STACK holds no key to the wallet and cannot move funds. `GET /v1/accounts/wallet-owner` reports whether the customer has become the owner of their agents' wallets, which is done in the Console. Caps are optional and need controls: with none, or without controls, the wallet's own balance is the limit. With "Ask me first" a payment waits for the owner: the first request is refused with `CONTROL_DENIED` and a `retry.ref`, and the agent asks again with the same payment and `X-Control-Ref` once the owner has approved it.

### PUT /v1/accounts/:id/wallet/caps

Body: `{ per_payment_cap_usdc?, daily_cap_usdc? }`, any positive amount, `null` removes a cap. Owner or admin only, needs controls; an agent is refused.

### PUT /v1/accounts/:id/budget

Body: `{ monthly_budget_cents }`, a whole number of USD cents above zero, or `null` to remove the budget. Owner or admin only; an agent is refused. Lowering applies at once and never needs controls. Setting a first budget or raising one needs controls (402 `CONTROLS_REQUIRED` otherwise). Raising or removing a budget is a loosening, so it needs the owner's approval in a signed-in browser (`account_control_loosen`): any other credential gets 403 `GOVERNANCE_APPROVAL_REQUIRED` with a link, and sends the approval back in `X-Governance-Approval`. The approval names the account and the old and new amounts. What the month has already spent is kept; a budget below it refuses further spend at once.

## RentAHuman

An agent can hire people for real-world tasks through your own RentAHuman account. STACK holds the account's key, sends the agent's calls with it and never shows it to the agent or its model. There is one RentAHuman connection per customer, granted to as many of your agents as you choose. Connect your own key the usual way, or let the agent open an account with its own wallet in two steps, because only the agent can sign for its wallet. The first step takes nothing; the second is a payment from the wallet and goes through the same Mission admission, meter, decider, caps and budget as `POST /v1/accounts/:id/wallet/payments`. STACK takes no fee for it.

- POST /v1/accounts/:id/rentahuman/join - { country, city?, agent_name?, accept_terms: true } asks RentAHuman what a new account costs and returns { join_id, amount_cents, pay_to, typed_data, wallet, expires_at }: the payment for the agent's wallet to sign. accept_terms true is you accepting RentAHuman's terms of service and privacy policy through your agent. One metered action; nothing is taken. The owner, an admin or an agent of the account may ask. 409 RENTAHUMAN_ALREADY_CONNECTED when you have a connection.
- POST /v1/accounts/:id/rentahuman/join/complete - { join_id, signed } sends the agent's signature. Only the account's own agent, under its Passport. RentAHuman's key goes into the vault and is never returned. A repeat with the same join_id answers the same and never pays twice. 502 RENTAHUMAN_PAYMENT_UNCONFIRMED means RentAHuman did not confirm a payment that may have been taken: do not pay again.
- POST /v1/accounts/:id/rentahuman/fund and POST .../fund/complete - the same two steps for topping up your RentAHuman wallet, { amount_cents } from 100 to 1,000,000, then { fund_id, signed }.
- GET /v1/accounts/:id/rentahuman - { connection } or null: its origin (owner_key or joined) and whether RentAHuman's events are registered (wake_registered; false while RentAHuman has not registered them: STACK keeps trying until it has, and the connection is kept; also false once the owner ended the webhook). It shows no key.

The agent calls RentAHuman through the connection with `stack_service_tools` and `stack_service_call_tool` (or the proxy: a POST to `/v1/proxy` with RentAHuman's MCP endpoint): searching people, posting and funding a bounty, reading applications and deliveries. It talks with the people it hires through the same call tool (`send_message`, `get_conversation`, `list_conversations`). A person who applies, delivers or writes wakes the agent with the wake source `service_event`, which carries the service, the kind of event and the ids and never what the person wrote; the agent reads the conversation and answers through the call tool. What RentAHuman returns is untrusted text, marked as such. Disconnecting the connection or erasing the account deletes the endpoint and revokes the key at RentAHuman first; the RentAHuman account and its balance stay yours.

## Getting paid

Card payments go through your own Stripe, and USDC payments for priced paths go into the agent's own wallet. STACK holds no money on either. Every payment is in the signed record.

- POST /v1/accounts/:id/payments/stripe - start the connection. For the account’s owner the answer carries connect_url, a single-use page where you paste a restricted Stripe key and the signing secret of the webhook endpoint (webhook_url) you add in Stripe. The key is never sent through the API, a chat or an agent. A full secret key, or a restricted key that reaches beyond creating payment links and checkout sessions and reading payments, is refused with 422 PAYMENT_KEY_REFUSED.
- GET and DELETE /v1/accounts/:id/payments/stripe - read the connection; disconnect it, which erases the key and turns off the active links (account admin only).
- POST .../payments/links { name, amount_minor, currency?, item?, after_payment_url? } and POST .../payments/checkout-sessions { name, amount_minor, success_url, cancel_url?, currency?, item? } - the agent creates a payment link or a checkout session. Return addresses must be on the agent’s own site. Without a connection the call is 409 PAYMENT_CONNECTION_REQUIRED.
- GET .../payments/links, POST .../payments/links/:linkId/deactivate, GET .../payments (rail, limit, cursor) and GET .../payments/:paymentId - links and the payments received on both rails.

Refunds are made where the money is: in your Stripe dashboard for a card payment, and by the agent paying the payer back from its own wallet for a USDC payment. STACK reads Stripe's refund and dispute events and updates the payment.
