Agentic Payments Quickstart

This walkthrough goes from nothing to an executed agent-drafted payment. It assumes an onboarded customer with a funded non-custodial wallet and an API key.

Alpha — the agentic surface is in early access. Run this walkthrough against the sandbox.

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.

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
  }'

{
  "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:

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. wallet_ids on the agent reflects the wallets that currently recognize it.

3. Draft a plan from a prompt

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:

{
  "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:

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 */ ]
  }'

{
  "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:

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.

{ "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.

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.

Playground

Documentation