> ## Documentation Index > Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Agentic Payments Quickstart > Create an agent, draft a payment plan in natural language, sign the mandate, and watch the payment fire This walkthrough goes from nothing to an executed agent-drafted payment. It assumes an onboarded customer with a funded [non-custodial wallet](/documentation/wallets) and an API key. **Alpha** — the agentic surface is in early access. Run this walkthrough against the [sandbox](/documentation/testing). ## 1. Create a hosted payment agent The agent gets its own signer key, managed by Dakota. That signer is the identity everything else binds to: mandates bind it, scheduled payments fire under it. ```bash theme={null} curl -X POST https://api.platform.dakota.xyz/payment-agents \ -H "X-API-Key: $DAKOTA_API_KEY" \ -H "X-Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "2vWxCustomer0000000000000000", "name": "My Bill Pay", "hosted": true }' ``` ```json theme={null} { "id": "2vWxAgent0000000000000000000", "name": "My Bill Pay", "customer_id": "2vWxCustomer0000000000000000", "hosted": true, "signer_id": "2vWxSigner000000000000000000", "signer_public_key": "BHkExampleKeyQm", "wallet_ids": [], "state": "active" } ``` Keep `signer_public_key` — it is what you grant wallet access to next. ## 2. Grant the agent wallet access The agent's signer must be **recognized** on the funding wallet before anything it drafts can fire. Recognition is signer-group membership, and there are two ways to grant it: **Option A — add the agent to a signer group already attached to the wallet (recommended).** A plain API call, no endorsement required — and the agent operates under whatever policy constraints that group already carries: ```bash theme={null} curl -X POST https://api.platform.dakota.xyz/signer-groups/2vWxGroup0000000000000000000/signers \ -H "X-API-Key: $DAKOTA_API_KEY" \ -H "X-Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "member_key": "BHkExampleKeyQm" }' ``` `member_key` is the agent's `signer_public_key` from step 1. **Option B — attach a signer group containing the agent's signer to the wallet.** Changing *which* groups govern a wallet is a wallet-state mutation, so it must be signed by the wallet's existing signers — an [endorsed request](/documentation/signing-guide#attach-signer-group-to-wallet). `wallet_ids` on the agent reflects the wallets that currently recognize it. ## 3. Draft a plan from a prompt ```bash theme={null} curl -X POST https://api.platform.dakota.xyz/payment-agents/2vWxAgent0000000000000000000/proposals \ -H "X-API-Key: $DAKOTA_API_KEY" \ -H "X-Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Pay Alice 10 USDC on base-sepolia 0xa11ce00000000000000000000000000000000001 every month on the 15th until Dec 26" }' ``` The reply contains conversational text plus zero or more `proposals` — each a summary and a concrete action series: ```json theme={null} { "reply": "Drafting a monthly payment to Alice — review and sign below.", "proposals": [ { "summary": "Pay Alice 10 USDC on base-sepolia, on the 15th of every month until Dec 2026 (7 payments)", "actions": [ { "type": "create_recipient", "create_recipient": { "name": "Alice" } }, { "type": "create_crypto_destination", "create_crypto_destination": { "address": "0xa11ce00000000000000000000000000000000001", "network_id": "base-sepolia" } }, { "type": "create_mandate", "create_mandate": { "rule": { "target_type": "recipient", "targets": ["Alice"], "network_id": "base-sepolia", "asset": "USDC", "max_per_tx": "10", "window": "MONTHLY", "max_count_per_target_in_window": 1 }, "valid_until": 1798675200 } }, { "type": "create_scheduled_payments", "create_scheduled_payments": { "amount": "10", "asset": "USDC", "dates": [1781481600, 1784073600, 1786752000, 1789430400, 1792022400, 1794700800, 1797292800] } } ] } ] } ``` Nothing has been created yet — a proposal is a draft your application shows the customer for review. The conversation is **stateless on the platform side** — the agent keeps no memory between calls. To refine a draft with a follow-up ("make it 12 USDC", "start in August"), resend the whole conversation so far in `messages`, in order, with the new turn appended (a `prompt` alone works only for the first turn, or as shorthand for the latest user message alongside `messages`). You can also attach an invoice (PDF or image, up to 8 MiB) and ask the agent to draft from it. ## 4. Accept — turn proposals into real objects Send the reviewed proposals back verbatim: ```bash theme={null} curl -X POST https://api.platform.dakota.xyz/instructions \ -H "X-API-Key: $DAKOTA_API_KEY" \ -H "X-Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "payment_agent_id": "2vWxAgent0000000000000000000", "proposals": [ /* the proposals array from step 3 */ ] }' ``` ```json theme={null} { "instruction_ids": ["2vWxInstruction0000000000000"], "mandates": [ { "id": "2vWxMandate00000000000000000", "status": "pending", "bound_signer_id": "2vWxSigner000000000000000000", "rule": { "target_type": "recipient", "targets": ["2vWxRecipient000000000000000"], "network_id": "base-sepolia", "asset": "USDC", "max_per_tx": "10", "window": "MONTHLY", "max_count_per_target_in_window": 1 }, "valid_until": 1798675200 } ] } ``` Actuation creates the recipient, destination, scheduled payments — and the mandate, in status `pending`. A failure mid-way rolls back the instruction's objects (no orphan payees). The response returns each drafted mandate **in full wire shape** (identical to `GET /mandates/{mandate_id}`), so your application can put it in front of the customer to sign immediately — no follow-up fetch or polling. `GET /instructions/{instruction_id}` remains available to audit what an instruction created. ## 5. The customer signs the mandate You already hold the pending mandate from step 4's response. It activates only when a recognized signer **other than the agent's** signs its canonical payload — this is the dual-control step that keeps spending authority with the customer: ```bash theme={null} curl -X POST https://api.platform.dakota.xyz/mandates/2vWxMandate00000000000000000/approve \ -H "X-API-Key: $DAKOTA_API_KEY" \ -H "X-Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "approver_public_key": "BHkApproverKeyQm", "signature": "MEUCIQExampleSignature" }' ``` How to construct `signature` — the exact payload bytes, canonicalization, and passkey support — is covered in [Mandate signing](/documentation/agentic-payments/mandate-signing). ```json theme={null} { "id": "2vWxMandate00000000000000000", "status": "active", "approved_by_signer_id": "2vWxApprover0000000000000000" } ``` ## 6. Payments fire on their dates From here the platform does the rest. On each scheduled date the payment is re-checked against the active mandate (caps, target, asset, validity) and sent through the standard money path. Watch progress either way: * **Poll:** `GET /scheduled-payments?status=scheduled,executed,failed` — each row carries its status, and once executed, the covering `mandate_id` and `wallet_transaction_id` for audit. * **Webhooks:** a success emits the standard `wallet.transaction.created`; a failure emits `scheduled_payment.failed` with a machine-readable `failure_code`. See [Agentic webhooks](/documentation/agentic-payments/webhooks). ## Where this leaves you One signed mandate now covers the whole monthly series — no re-signing per payment, and the agent still cannot exceed `10 USDC` per transaction, once per month, to Alice alone. To grant more, draft more and sign again; to end it, `POST /mandates/{mandate_id}/cancel` or revoke the agent.