Skip to main content

Getting Started

This walks through the shortest path from nothing to a confirmed disbursement: register as a Funding Party, mint a credential, stand up an agent, and send your first payment. Each step links out to the page that covers it in depth.

1. Onboard as a Funding Party​

One-time, SIWX-session-gated. Registers your Funding Party account and its funder wallet, and in the same call uploads a roster of recipient wallet addresses:

curl -X POST https://<platform-host>/api/employers/onboard \
  -H "Cookie: sessionId=<your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "email": "finance@acme.example",
    "wallet_addresses": ["0xAbC123...", "0xDeF456..."]
  }'
{
  "success": true,
  "alreadyRegistered": false,
  "roster": { "requested": 2, "employeesAdded": 2, "whitelist": { "deferred": true } }
}

roster.employeesAdded is a literal field name from the underlying API; it counts the recipients just added to your roster. Onboarding itself issues no credential; mint one next.

roster.whitelist.deferred: true is expected; see the next step.

1b. Mint an API key​

curl -X POST https://<platform-host>/api/employers/keys \
  -H "Cookie: sessionId=<your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "capability": "disburse", "name": "payroll-scheduler" }'
{
  "success": true,
  "id": 12,
  "apiKey": "lgk_live_...",
  "keyPrefix": "lgk_live_ab12",
  "capability": "disburse",
  "name": "payroll-scheduler",
  "createdAt": "2026-08-17T12:00:00.000Z"
}

Store apiKey now: it's shown exactly once. It's the credential your disbursement agent uses to authorize every disburse call. Keys are capability-scoped and additive: minting this one doesn't revoke any other key on your wallet, and you can mint separate ones later for account operations (transfer, send). Details on how this key is used, and the other credentials involved, are in Authentication & API Access.

2. Recipients become eligible at first login​

You don't whitelist recipients directly. A recipient's wallet public key (W, distinct from the address you just submitted) is only recoverable from their own sign-in signature, so eligibility is written automatically the first time each recipient signs in. If you're integrating before recipients have signed in yet, or need to repair a gap, see Eligibility → Repairing or bulk-draining eligibility.

If your recipients' wallets are in MPC custody, they will never sign in

That login is where W comes from, so waiting for it never resolves — and the same signature is what would give them an encryption key P, which an MPC signer cannot produce reproducibly either. Attest both yourself instead: Employees in DFNS custody.

3. Run a disbursement agent​

The agent is a process you run on your own infrastructure; it needs a real GPU accelerator and outbound reach to the platform's /agent-edge. Minimum configuration:

export DISBURSE_PLATFORM_URL="https://<platform-host>/agent-edge"
export DISBURSE_PLATFORM_TOKEN="<agent-edge token for your deployment>"
export DISBURSE_PLATFORM_VERIFY_URL="https://<platform-host>/api/employers/verify-key"
export DISBURSE_FUNDER_PRIVATE_KEY="<dev only, see Authentication for production signers>"

disburse-agent

Confirm it's ready before sending traffic:

curl http://127.0.0.1:8787/api/readyz

Full configuration reference, including production-grade signer options (enclave, Fireblocks, DFNS), is in Disbursement → Configuring the agent.

Running the funder in MPC custody

DISBURSE_FUNDER_PRIVATE_KEY is a development shortcut. If your funder key lives in DFNS, follow Delegated Custody with DFNS instead of this step: the key stays inside your DFNS organization, and the agent is joined by a second process that approves what it asks to sign. The rest of this walkthrough is unchanged.

4. Dry-run a batch​

Validate recipients and allowance without proving or settling anything:

curl -X POST http://127.0.0.1:8787/api/validate \
  -H "Authorization: Bearer lgk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "recipients": [{ "recipientAddress": "0xAbC123...", "amount": "500000" }]
  }'

5. Send your first disbursement​

curl -X POST http://127.0.0.1:8787/api/disburse \
  -H "Authorization: Bearer lgk_live_..." \
  -H "Idempotency-Key: first-run-1" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "recipients": [{ "recipientAddress": "0xAbC123...", "amount": "500000" }]
  }'

Poll the returned statusUrl until the job reaches a terminal state:

curl http://127.0.0.1:8787/api/disburse/first-run-1 \
  -H "Authorization: Bearer lgk_live_..."

Full request/response shapes, batching behavior, and error handling are in Disbursement.

Next steps​

  • Authentication & API Access: every credential in this flow, what each one gates, and how to rotate them.
  • Eligibility: whitelist and blacklist mechanics in detail.
  • Disbursement: the full /api/disburse reference and agent configuration.
  • Account Operations: enroll your own wallet as a pool subject, read its balance, transfer within the pool, or withdraw out to a chain address.
  • Delegated Custody with DFNS: the funder, the holder, and recipients who never sign in — all with no private key on the agent host.
  • Glossary: quick lookups for terms like SIWX, note commitment, and dual signature.