# Authentication
Source: https://docs.toku.com/api/authentication

How to authenticate with the Toku API using personal API tokens

## Overview

The Toku API uses **Bearer token authentication**. Every request must include a personal API token in the `Authorization` header, along with a role type header specifying the permission context.

## Getting Your API Token

<Steps>
  <Step title="Create a token">
    Call the `createUserApiToken` endpoint with your existing session credentials, or ask a Toku administrator to provision one for you.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createUserApiToken \
      -H "Authorization: Bearer EXISTING_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json"
    ```

    The response includes your new API token. **Store it securely** — it cannot be retrieved again.
  </Step>

  <Step title="Use the token">
    Include the token in every API request:

    ```bash theme={null}
    curl https://app.toku.com/api/tokuApi/v1/listGrants \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN"
    ```
  </Step>

  <Step title="Refresh when needed">
    Tokens expire after 30 days. Refresh before expiry:

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/refreshUserApiToken \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json"
    ```
  </Step>
</Steps>

## Required Headers

| Header          | Required            | Description                              |
| --------------- | ------------------- | ---------------------------------------- |
| `Authorization` | Yes                 | `Bearer YOUR_API_TOKEN`                  |
| `x-role-type`   | Yes                 | Role context for the request (see below) |
| `Content-Type`  | For POST/PUT/DELETE | Must be `application/json`               |

## Role Types

The `x-role-type` header determines what permissions your request has. Your API token must belong to a user with the specified role in the organization.

| Role               | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| `CLIENT_ORG_ADMIN` | Full administrative access to the organization. Use this for most integrations. |
| `PAYROLL_ADMIN`    | Access to payroll and settlement operations                                     |
| `FINANCE_ADMIN`    | Access to financial reporting and payment operations                            |
| `INVESTOR`         | Read access to investment and warrant data                                      |

<Tip>
  For most 3rd party integrations, `CLIENT_ORG_ADMIN` is the recommended role type. It provides full access to grants, wallets, employees, and organization settings.
</Tip>

## Token Scoping

Each API token is scoped to a single organization. If you manage multiple organizations, you need a separate token for each.

The token inherits the permissions of the user who created it. If the user's role is revoked, the token stops working.

## Security Best Practices

* **Never expose tokens in client-side code** — API tokens should only be used in server-to-server communication
* **Rotate tokens regularly** — use `refreshUserApiToken` to get a new token before the current one expires
* **Use the minimum required role** — if your integration only needs to read grants, consider using a role with read-only access
* **Monitor usage** — Toku logs all API access by token for audit purposes

## Error Responses

| Status | Meaning                                                    |
| ------ | ---------------------------------------------------------- |
| `401`  | Token is missing, invalid, or expired                      |
| `403`  | Token is valid but the user doesn't have the required role |
| `429`  | Rate limit exceeded (100 req/min per IP)                   |

```json theme={null}
// 401 Unauthorized
{
  "error": "Invalid token or insufficient permissions",
  "details": "Token expired at 2026-03-01T00:00:00.000Z. Please refresh your API token."
}

// 403 Forbidden
{
  "error": "User does not have role CLIENT_ORG_ADMIN in organization"
}
```


# Allocate Custody Wallets to Grant
Source: https://docs.toku.com/api/endpoints/custody/add-custody-allocations

POST /addCustodyAllocationsToGrant
Assigns custody wallets to a grant with token allocation amounts.



# Configure Anchorage Integration
Source: https://docs.toku.com/api/endpoints/custody/configure-anchorage

POST /updateAnchorageIntegration
Saves Anchorage API credentials, vault, asset, and network configuration.



# Create Anchorage Custody Wallet
Source: https://docs.toku.com/api/endpoints/custody/create-anchorage-wallet

POST /createAnchorageCustodyWallet
Creates new custody wallets in Anchorage.



# Create Fireblocks Custody Wallet
Source: https://docs.toku.com/api/endpoints/custody/create-fireblocks-wallet

POST /createFireblocksCustodyWallet
Creates new vault accounts in Fireblocks.



# Delete Anchorage Integration
Source: https://docs.toku.com/api/endpoints/custody/delete-anchorage

POST /deleteAnchorageIntegration
Removes Anchorage integration from the organization.



# Delete Custody Allocations
Source: https://docs.toku.com/api/endpoints/custody/delete-custody-allocations

POST /deleteCustodyAllocations
Removes custody wallet allocations.



# Delete Fireblocks Integration
Source: https://docs.toku.com/api/endpoints/custody/delete-fireblocks-integration

POST /deleteFireblocksIntegration
Removes Fireblocks integration from the organization.



# Delete Safe Integration
Source: https://docs.toku.com/api/endpoints/custody/delete-safe-integration

POST /deleteGnosisSafeIntegration
Removes Safe/Gnosis integration from the organization.



# List All Custody Wallets
Source: https://docs.toku.com/api/endpoints/custody/get-all-custody-wallets

GET /getAllCustodyWallets
Returns all custody wallets across all providers (Fireblocks, Anchorage, Safe).



# Get Anchorage Public Key
Source: https://docs.toku.com/api/endpoints/custody/get-anchorage-public-key

GET /getAnchorageIntegrationPublicKey
Returns the ED25519 signer public key for Anchorage integration.



# List Anchorage Vaults
Source: https://docs.toku.com/api/endpoints/custody/get-anchorage-vaults

GET /getAnchorageVaults
Returns available vaults in your Anchorage account.



# Get Custody Wallet Count
Source: https://docs.toku.com/api/endpoints/custody/get-custody-wallet-count

GET /getCustodyWalletCount
Returns wallet count statistics by custody provider.



# Get Custody Wallets for Grant
Source: https://docs.toku.com/api/endpoints/custody/get-custody-wallets-for-grant

GET /getCustodyWalletsForGrant
Returns custody wallets allocated to a specific grant.



# Get Fireblocks Integration
Source: https://docs.toku.com/api/endpoints/custody/get-fireblocks-integration

GET /getFireblocksIntegration
Returns Fireblocks integration status and configuration.



# List Fireblocks Vault Accounts
Source: https://docs.toku.com/api/endpoints/custody/get-fireblocks-vaults

GET /getFireblocksVaultAccounts
Returns vault accounts from your Fireblocks account.



# Get Safe Integration
Source: https://docs.toku.com/api/endpoints/custody/get-safe-integration

GET /getGnosisSafeIntegration
Returns Safe/Gnosis integration status including proposer address, connected Safe, and balance.



# List Safe Wallets
Source: https://docs.toku.com/api/endpoints/custody/get-safe-wallets

GET /getSafeWallets
Returns paginated list of Safe multisig wallets.



# Link Existing Anchorage Wallet
Source: https://docs.toku.com/api/endpoints/custody/link-anchorage-wallet

POST /linkExistingAnchorageCustodyWallet
Links an existing Anchorage wallet to TGA.



# Link Existing Fireblocks Vault
Source: https://docs.toku.com/api/endpoints/custody/link-fireblocks-wallet

POST /linkExistingFireblocksCustodyWallet
Links an existing Fireblocks vault account to TGA.



# Refresh Custody Wallet Balances
Source: https://docs.toku.com/api/endpoints/custody/refresh-custody-balances

POST /bulkUpdateCustodyWalletBalance
Fetches latest balances from custody providers for specified wallets.



# Save Fireblocks Integration
Source: https://docs.toku.com/api/endpoints/custody/save-fireblocks-integration

POST /saveFireblocksIntegration
Configures Fireblocks API credentials and tests the connection.



# Test Safe Connection
Source: https://docs.toku.com/api/endpoints/custody/test-safe-connection

POST /testGnosisSafeConnection
Verifies Safe exists, proposer is registered as delegate, and syncs webhooks.



# Update Custody Allocations
Source: https://docs.toku.com/api/endpoints/custody/update-custody-allocations

POST /updateCustodyAllocations
Modifies allocation amounts for existing custody wallet assignments.



# Add Manual Tax Details
Source: https://docs.toku.com/api/endpoints/distributions/add-manual-tax-details

POST /addManualTaxDetails
Adds manual tax withholding details to approved schedules.



# Add No-Tax Details
Source: https://docs.toku.com/api/endpoints/distributions/add-no-tax-details

POST /addNoTaxDetails
Marks schedules as tax-exempt with FMV tracking only.



# Batch Approve Schedules
Source: https://docs.toku.com/api/endpoints/distributions/batch-approve-schedules

POST /batchApproveSchedules
Approves a batch of pending vestings, lockups, or warrant lockups.



# Finalize Tax Details
Source: https://docs.toku.com/api/endpoints/distributions/batch-finalize-tax

POST /batchFinalizeTaxDetails
Approves and finalizes tax details, moving schedules to ready-for-settlement.



# Batch Record Settlements
Source: https://docs.toku.com/api/endpoints/distributions/batch-record-settlements

POST /batchSettleSchedules
Records multiple completed settlements in one call.



# Reject Tax Details
Source: https://docs.toku.com/api/endpoints/distributions/batch-reject-tax

POST /batchRejectTaxDetails
Rejects tax details, returning schedules to tax grouping stage.



# Batch Update FMV
Source: https://docs.toku.com/api/endpoints/distributions/batch-update-fmv

POST /batchUpdateFMV
Updates fair market value for tax references before finalization.



# Bulk Distribution Processing
Source: https://docs.toku.com/api/endpoints/distributions/bulk-distribution-processing

POST /bulkDistributionProcessing
Process multiple schedules with per-schedule tax method (NO_TAX or MANUAL_TAX).



# Can Submit Settlement
Source: https://docs.toku.com/api/endpoints/distributions/can-submit-settlement

GET /canSubmitScheduleSettlement
Checks if a settlement can be submitted to the custody provider.



# Get All Settlements
Source: https://docs.toku.com/api/endpoints/distributions/get-all-settlements

GET /getAllSettlementsForOrg
Returns paginated settlement history for the organization.



# Get Pending Schedules
Source: https://docs.toku.com/api/endpoints/distributions/get-pending-schedules

GET /getPendingSchedules
Returns vestings, lockups, and warrant lockups pending approval.



# Get Schedules Pending Settlement
Source: https://docs.toku.com/api/endpoints/distributions/get-pending-settlement

GET /getSchedulesPendingSettlement
Returns schedules with finalized tax, ready for settlement execution.



# Get Processing Schedules Count
Source: https://docs.toku.com/api/endpoints/distributions/get-processing-count

GET /getProcessingSchedulesCount
Returns count of schedules currently being processed.



# Get Settlement Status
Source: https://docs.toku.com/api/endpoints/distributions/get-settlement-status

GET /getScheduleSettlementStatus
Returns the current settlement status for a tax reference.



# Get Schedules Awaiting Tax Finalization
Source: https://docs.toku.com/api/endpoints/distributions/get-tax-finalization

GET /getSchedulesAwaitingTaxFinalization
Returns schedules with tax details pending admin approval.



# Get Schedules Awaiting Tax Grouping
Source: https://docs.toku.com/api/endpoints/distributions/get-tax-grouping

GET /getSchedulesAwaitingTaxGrouping
Returns approved schedules grouped by recipient, ready for tax details.



# Record Settlement
Source: https://docs.toku.com/api/endpoints/distributions/record-settlement

POST /settleTaxReference
Records a completed on-chain settlement with transaction hash.



# Retry Failed Settlement
Source: https://docs.toku.com/api/endpoints/distributions/retry-settlement

POST /retryScheduleSettlement
Retries a failed settlement with the same custody provider.



# Revert Schedule Approval
Source: https://docs.toku.com/api/endpoints/distributions/revert-schedule-approval

POST /revertScheduleApproval
Reverts approved schedules back to pending status.



# Revert Tax Details
Source: https://docs.toku.com/api/endpoints/distributions/revert-tax-details

POST /revertTaxDetails
Reverts finalized tax details back to tax grouping stage.



# Submit Settlement to Custody
Source: https://docs.toku.com/api/endpoints/distributions/submit-settlement

POST /submitScheduleSettlement
Submits a settlement to your custody provider (Fireblocks or Anchorage) for on-chain execution.



# Batch Update Roles
Source: https://docs.toku.com/api/endpoints/employees/batch-update-roles

PUT /batchUpdateRoleInOrg
Updates multiple user roles in a single request.



# Create User Role in Org
Source: https://docs.toku.com/api/endpoints/employees/create-user-role

POST /createUserRoleInOrg
Creates a new user and assigns them a role in your organization.



# Get User Role in Org
Source: https://docs.toku.com/api/endpoints/employees/get-user-role

GET /getUserRoleInOrg
Retrieves role details for a user in the organization.



# Update User Role in Org
Source: https://docs.toku.com/api/endpoints/employees/update-user-role

PUT /updateUserRoleInOrg
Updates an existing user role.



# Add Single Grant
Source: https://docs.toku.com/api/endpoints/grants/add-single-grant

POST /addSingleGrant
Creates a new token grant for an employee.



# Bulk Add Grants
Source: https://docs.toku.com/api/endpoints/grants/bulk-add-grants

POST /bulkAddGrants
Creates multiple grants in a single request.



# Create Grant Configuration
Source: https://docs.toku.com/api/endpoints/grants/create-grant-configuration

POST /createGrantConfiguration
Creates a grant type template (RTU, RTA, TPA, TOKEN_BONUS) for your organization.



# Create Grant for New Hire
Source: https://docs.toku.com/api/endpoints/grants/create-grant-for-new-hire

POST /createGrantForNewHire
Creates a grant for a new hire, optionally creating the user role in the organization.



# Create Grant Template
Source: https://docs.toku.com/api/endpoints/grants/create-grant-template

POST /createGrantTemplate
Creates a vesting schedule template with custom tranches.



# Get Employee Grants
Source: https://docs.toku.com/api/endpoints/grants/get-employee-grants

GET /getEmployeeGrants
Returns all grants for a specific employee. Provide either payrollEmployeeID or externalEmployeeID.



# Get Grant Details
Source: https://docs.toku.com/api/endpoints/grants/get-grant-by-id

GET /getGrantByID
Returns full details for a single grant including vesting schedule, wallet info, and configuration.



# List Grant Templates
Source: https://docs.toku.com/api/endpoints/grants/get-grant-templates

GET /getGrantTemplates
Returns vesting schedule templates for the organization.



# Get Grant Vesting Schedule
Source: https://docs.toku.com/api/endpoints/grants/get-grant-vesting-data

GET /getGrantVestingData
Returns the vesting schedule with individual tranche dates, amounts, and settlement status.



# Get Payroll Employee ID
Source: https://docs.toku.com/api/endpoints/grants/get-payroll-employee-id

GET /getPayrollEmployeeID
Resolves the payroll employee identifier from an external employee ID.



# List Grant Configurations
Source: https://docs.toku.com/api/endpoints/grants/list-grant-configurations

GET /listGrantConfigurations
Returns all grant configuration templates for your organization.



# List Grants
Source: https://docs.toku.com/api/endpoints/grants/list-grants

GET /listGrants
Returns all grants for the authenticated organization. Filter by externalEmployeeID in the response to get grants for a specific employee.



# Revert Employee Grant Termination
Source: https://docs.toku.com/api/endpoints/grants/revert-employee-grant-termination

POST /revertEmployeeGrantTermination
Reverts a single terminated grant for an employee.



# Revert Employee Grants (Bulk)
Source: https://docs.toku.com/api/endpoints/grants/revert-employee-grants

POST /revertEmployeeGrants
Reverts multiple terminated grants for an employee.



# Revert Grant Termination
Source: https://docs.toku.com/api/endpoints/grants/revert-grant-termination

POST /revertGrantTermination
Reverts a previously terminated grant and regenerates vestings.



# Terminate Employee Grants
Source: https://docs.toku.com/api/endpoints/grants/terminate-employee-grants

POST /terminateEmployeeGrants
Terminates grants for an employee. If grantIDs omitted, terminates all active grants.



# Terminate Grant
Source: https://docs.toku.com/api/endpoints/grants/terminate-grant

POST /terminateGrant
Terminates a grant by recalculating vestings up to the termination date.



# Terminate Grants (Bulk)
Source: https://docs.toku.com/api/endpoints/grants/terminate-grants

POST /terminateGrants
Terminates multiple grants for an employee by external ID.



# Update Pending Grant
Source: https://docs.toku.com/api/endpoints/grants/update-pending-grant

POST /updatePendingGrant
Updates a grant that is still in PENDING status (not yet accepted by recipient).



# Mark Invoice Payment as Settled
Source: https://docs.toku.com/api/endpoints/invoices/mark-payment-settled

POST /markInvoicePaymentAsSettled
Marks an invoice payment as settled.



# Submit Bulk Invoice Payments
Source: https://docs.toku.com/api/endpoints/invoices/submit-bulk-payments

POST /submitBulkInvoicePayments
Submits multiple invoice payments for processing.



# Create Document
Source: https://docs.toku.com/api/endpoints/organization/create-document

POST /createDocument
Creates a document record linked to a recipient and optionally a grant.



# List Documents (Admin)
Source: https://docs.toku.com/api/endpoints/organization/get-documents-admin

GET /getDocumentsAdmin
Returns all documents in the organization, optionally filtered by recipient.



# List My Documents
Source: https://docs.toku.com/api/endpoints/organization/get-my-documents

GET /getMyDocuments
Returns documents visible to the authenticated user.



# Get Organization Wallet Info
Source: https://docs.toku.com/api/endpoints/organization/get-org-wallet-info

GET /getOrgWalletInfo
Returns wallet configuration details for the organization.



# Health Check
Source: https://docs.toku.com/api/endpoints/organization/hello

GET /hello
Returns a Hello World message to verify API connectivity.



# Send Client Admin Onboarding Email
Source: https://docs.toku.com/api/endpoints/organization/send-client-admin-onboarding-email

POST /sendClientAdminOnboardingEmail
Sends an onboarding email to a client admin.



# Send Onboarding Email
Source: https://docs.toku.com/api/endpoints/organization/send-onboarding-email

POST /sendOnboardingEmail
Sends an onboarding/activation email to a user.



# Update Token Address
Source: https://docs.toku.com/api/endpoints/organization/update-org-token-address

POST /updateOrgTokenAddress
Updates the token contract address for your organization.



# Update Test Transaction Configuration
Source: https://docs.toku.com/api/endpoints/organization/update-test-txn-config

PUT /updateTestTransactionConfiguration
Updates the test transaction configuration settings.



# Delete Network
Source: https://docs.toku.com/api/endpoints/tokens-networks/delete-network

DELETE /deleteNetwork
Removes a network from the organization.



# Delete Wallet Type
Source: https://docs.toku.com/api/endpoints/tokens-networks/delete-wallet-type

DELETE /deleteWalletType
Removes a wallet type from the organization.



# Get Networks
Source: https://docs.toku.com/api/endpoints/tokens-networks/get-networks

GET /getNetworks
Returns blockchain networks configured for your organization.



# Get Networks (v2)
Source: https://docs.toku.com/api/endpoints/tokens-networks/get-networks-new

GET /getNetworksNew
Returns networks with token type details using the new API format.



# Get Token Types
Source: https://docs.toku.com/api/endpoints/tokens-networks/get-token-types

GET /getTokenTypes
Returns token types configured for your organization.



# Get Token Types (v2)
Source: https://docs.toku.com/api/endpoints/tokens-networks/get-token-types-new

GET /getTokenTypesNew
Returns token types with network details using the new API format.



# Get Wallet Types
Source: https://docs.toku.com/api/endpoints/tokens-networks/get-wallet-types

GET /getWalletTypes
Returns wallet types configured for your organization.



# Configure Wallet Distribution for Grant
Source: https://docs.toku.com/api/endpoints/wallet-distribution/configure-grant-distribution

POST /configureWalletRefsDistributionForGrant
Sets how tokens are distributed across wallets for a specific grant.



# Get Wallet References for All Grants
Source: https://docs.toku.com/api/endpoints/wallet-distribution/get-wallet-refs-grants

GET /getAllWalletReferencesForAllGrants
Returns wallet references linked to all grants.



# Get Wallet References with Networks
Source: https://docs.toku.com/api/endpoints/wallet-distribution/get-wallet-refs-networks

GET /getWalletReferencesWithNetworks
Returns wallet references with their associated network information.



# Set Token Wallet Distribution
Source: https://docs.toku.com/api/endpoints/wallet-distribution/set-token-distribution

POST /setTokenWalletRefsDistribution
Configures token-level wallet distribution settings.



# Add Test Transaction
Source: https://docs.toku.com/api/endpoints/wallet-verification/add-test-transaction

POST /addTestTransaction
Creates a test transaction for wallet verification.



# Add Test Transaction to Wallet
Source: https://docs.toku.com/api/endpoints/wallet-verification/add-test-txn-to-wallet

POST /addTestTxnToWallet
Attaches a test transaction to a wallet request.



# Get Pending Wallet Test Requests
Source: https://docs.toku.com/api/endpoints/wallet-verification/get-pending-test-requests

GET /getPendingWalletTestRequests
Returns wallet requests where test transactions are still pending.



# Get Test Transaction Approval Pending Wallets
Source: https://docs.toku.com/api/endpoints/wallet-verification/get-test-txn-pending

GET /getTestTxnApprovalPendingWallets
Returns wallets where test transactions are awaiting admin approval.



# Get Verified Wallet Test Requests
Source: https://docs.toku.com/api/endpoints/wallet-verification/get-verified-test-requests

GET /getVerifiedWalletTestRequests
Returns wallet requests where the test transaction has been verified.



# Process Bulk Test Transactions
Source: https://docs.toku.com/api/endpoints/wallet-verification/process-bulk-test

POST /processBulkTestTransactions
Processes test transactions for multiple wallets.



# Resend Test Transaction Email
Source: https://docs.toku.com/api/endpoints/wallet-verification/resend-test-email

POST /resendTestTxnEmailToWalletOwner
Resends the test transaction notification email to the wallet owner.



# Send Test Transaction
Source: https://docs.toku.com/api/endpoints/wallet-verification/send-test-transaction

POST /sendTestTransaction
Sends a test transaction to verify wallet ownership.



# Add Wallet
Source: https://docs.toku.com/api/endpoints/wallets/add-wallet

POST /addWallet
Adds a new wallet for a recipient.



# Approve Wallet
Source: https://docs.toku.com/api/endpoints/wallets/approve-wallet

POST /approveWallet
Approves a wallet after verification.



# Approve Wallet Request
Source: https://docs.toku.com/api/endpoints/wallets/approve-wallet-request

POST /approveWalletRequest
Approves a pending wallet request.



# Bulk Upload Wallets
Source: https://docs.toku.com/api/endpoints/wallets/bulk-upload-wallets

POST /bulkUploadMultipleWallets
Uploads multiple wallets in a single request.



# Cancel Wallet Request
Source: https://docs.toku.com/api/endpoints/wallets/cancel-wallet-request

POST /cancelWalletRequest
Cancels a pending wallet request.



# Get All Historical Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-all-historical-wallets

GET /getAllHistoricalWallets
Returns all historical wallets across the organization.



# List All Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-all-wallets

GET /getAllWallets
Returns all wallets across all recipients in your organization.



# Get All Wallets for All Recipients
Source: https://docs.toku.com/api/endpoints/wallets/get-all-wallets-for-recipients

GET /getAllWalletsForAllRecipients
Returns wallets for all grant recipients in the organization.



# Get Current Wallet
Source: https://docs.toku.com/api/endpoints/wallets/get-current-wallet

GET /getCurrentWallet
Returns the current active wallet for the authenticated user's role.



# Get Employee Historical Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-employee-historical-wallets

GET /getEmployeeHistoricalWallets
Returns historical wallets for a specific employee.



# Get Employee Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-employee-wallets

GET /getEmployeeWallets
Returns current wallets for a specific employee.



# Get Historical Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-historical-wallets

GET /getHistoricalWallets
Returns historical (deactivated) wallets for the authenticated user's role.



# Get Pending Wallet Request
Source: https://docs.toku.com/api/endpoints/wallets/get-pending-wallet-request

GET /getPendingWalletRequest
Returns the pending wallet request for the authenticated user.



# Get All Pending Wallet Requests
Source: https://docs.toku.com/api/endpoints/wallets/get-pending-wallet-requests

GET /getPendingWalletRequests
Returns all pending wallet requests in the organization.



# Get Pending Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-pending-wallets

GET /getPendingWallets
Returns wallets awaiting approval.



# Get User Current Wallets
Source: https://docs.toku.com/api/endpoints/wallets/get-user-current-wallets

GET /getUserCurrentWallets
Returns all current wallets, optionally filtered by roleInOrgID.



# Deactivate Wallet
Source: https://docs.toku.com/api/endpoints/wallets/mark-wallet-not-current

POST /markWalletAsNotCurrent
Deactivates a wallet (moves it to historical).



# Reactivate Wallet
Source: https://docs.toku.com/api/endpoints/wallets/reactivate-wallet

POST /reactivateWallet
Reactivates a previously deactivated wallet.



# Reject Wallet
Source: https://docs.toku.com/api/endpoints/wallets/reject-wallet

POST /rejectWallet
Rejects a wallet submission.



# Reject Wallet Request
Source: https://docs.toku.com/api/endpoints/wallets/reject-wallet-request

POST /rejectWalletRequest
Rejects a pending wallet request.



# Update Wallet
Source: https://docs.toku.com/api/endpoints/wallets/update-wallet

POST /updateWallet
Updates an existing wallet.



# Errors & Rate Limits
Source: https://docs.toku.com/api/errors

Error codes, rate limits, and how to handle API errors

## HTTP Status Codes

| Status | Meaning               | Common Cause                                        |
| ------ | --------------------- | --------------------------------------------------- |
| `200`  | Success               | Request completed successfully                      |
| `400`  | Bad Request           | Invalid request body or missing required fields     |
| `401`  | Unauthorized          | Missing, invalid, or expired API token              |
| `403`  | Forbidden             | Valid token but insufficient role permissions       |
| `404`  | Not Found             | Resource doesn't exist or operation name is invalid |
| `405`  | Method Not Allowed    | Wrong HTTP method for the endpoint                  |
| `429`  | Too Many Requests     | Rate limit exceeded                                 |
| `500`  | Internal Server Error | Unexpected server error                             |

## Error Response Format

All errors return a JSON object with an `error` field and an optional `details` field:

```json theme={null}
{
  "error": "Short error message",
  "details": "Additional information to aid debugging"
}
```

## Common Errors

### Authentication Errors (401)

```json theme={null}
// Missing token
{ "error": "Token is required" }

// Expired token
{
  "error": "Invalid token or insufficient permissions",
  "details": "Token expired at 2026-03-01T00:00:00.000Z. Please refresh your API token."
}

// Invalid token
{
  "error": "Invalid token or insufficient permissions",
  "details": "No PersonalToken found"
}
```

### Authorization Errors (403)

```json theme={null}
// Wrong role
{
  "error": "Invalid token or insufficient permissions",
  "details": "User does not have role CLIENT_ORG_ADMIN in organization abc-123"
}
```

### Validation Errors (400)

```json theme={null}
// Missing required field
{
  "error": "grantID is required"
}

// Invalid format
{
  "error": "terminationDate must be a valid ISO 8601 date"
}
```

### Not Found (404)

```json theme={null}
// Unknown operation
{
  "error": "No external API operation found for unknownEndpoint"
}

// Resource not found
{
  "error": "Grant not found"
}
```

## Rate Limiting

The API enforces **100 requests per minute** per IP address.

When rate limited, you'll receive:

```json theme={null}
// 429 Too Many Requests
{
  "error": "Too Many Requests"
}
```

### Handling Rate Limits

* Implement exponential backoff when you receive a `429`
* Batch operations where possible (e.g., use `terminateEmployeeGrants` instead of multiple individual calls)
* Cache responses that don't change frequently (e.g., `listGrantConfigurations`, `getTokenTypes`)

## Best Practices

1. **Always check the status code** before parsing the response body
2. **Log error details** — the `details` field often contains actionable information
3. **Implement retries** for `500` errors with exponential backoff
4. **Don't retry** `400`, `401`, `403`, or `404` errors — fix the request first
5. **Handle token expiry gracefully** — call `refreshUserApiToken` when you get a `401` with an expiry message


# Integration Best Practices
Source: https://docs.toku.com/api/guides/best-practices

Rate limiting, caching, error handling, and polling strategies

## No Pagination

List endpoints (`listGrants`, `getAllWallets`, etc.) return **all results** in a single response. There are no `limit`, `offset`, or cursor parameters.

**Implications:**

* Cache responses locally and refresh periodically
* Don't call list endpoints on every page load in your UI
* For large organizations (1000+ grants), responses may be several MB

```typescript theme={null}
// Good: cache and refresh every 5 minutes
let grantCache = [];
let lastFetch = 0;

async function getGrants() {
  if (Date.now() - lastFetch > 5 * 60 * 1000) {
    grantCache = await tokuAPI('GET', 'listGrants');
    lastFetch = Date.now();
  }
  return grantCache;
}
```

***

## Rate Limiting

The API enforces **100 requests per minute** per IP address.

**Strategy:**

* Batch operations where possible (`batchUpdateRoleInOrg`, `bulkUploadMultipleWallets`, `processBulkTestTransactions`)
* Space out polling intervals (5-15 minutes, not seconds)
* Implement exponential backoff on `429` responses

```typescript theme={null}
async function tokuAPIWithRetry(method: string, endpoint: string, body?: any, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(`${TOKU_BASE_URL}/${endpoint}`, {
      method, headers, body: body ? JSON.stringify(body) : undefined
    });

    if (res.status === 429) {
      const waitMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, waitMs));
      continue;
    }

    if (res.status >= 500) {
      const waitMs = Math.pow(2, attempt) * 2000;
      await new Promise(r => setTimeout(r, waitMs));
      continue;
    }

    return res.json();
  }
  throw new Error('Max retries exceeded');
}
```

***

## Token Refresh

API tokens expire after **30 days**. After refresh, the old token has a **7-day grace period**.

```typescript theme={null}
// Refresh before expiry
const { personalToken } = await tokuAPI('POST', 'refreshUserApiToken', {
  email: 'admin@company.com',
  orgID: 'your-org-id',
  roleInOrgID: 'your-role-in-org-id'
});

// Store the new token
const newToken = personalToken.token;
const expiresAt = personalToken.expiresAt;
```

<Tip>
  Set a calendar reminder or cron job to refresh 7 days before expiry. The old token continues working for 7 days after refresh, so there's no downtime during rotation.
</Tip>

***

## Error Handling

### Don't retry these (fix the request):

* `400` Bad Request — invalid parameters
* `401` Unauthorized — token expired or invalid
* `403` Forbidden — wrong role for this endpoint
* `404` Not Found — resource doesn't exist

### Retry these (with backoff):

* `429` Too Many Requests — rate limited
* `500` Internal Server Error — transient failure

### Common error patterns:

```typescript theme={null}
try {
  await tokuAPI('POST', 'terminateGrant', { grantID, terminationDate });
} catch (err) {
  if (err.message.includes('already terminated')) {
    // Grant was already terminated — idempotent, safe to ignore
  } else if (err.message.includes('not found')) {
    // Grant doesn't exist — check your grantID
  } else {
    throw err; // Unexpected error
  }
}
```

***

## Idempotency

| Operation                           | Idempotent? | Notes                                                                       |
| ----------------------------------- | ----------- | --------------------------------------------------------------------------- |
| `listGrants`, `getAllWallets`, etc. | Yes         | GET requests are always safe to retry                                       |
| `terminateGrant`                    | Partially   | Terminating an already-terminated grant returns an error but causes no harm |
| `addSingleGrant`                    | No          | Creates a new grant each time — use unique names to detect duplicates       |
| `createUserRoleInOrg`               | No          | Creating a user with an existing email may fail or create duplicates        |
| `approveWalletRequest`              | Partially   | Approving an already-approved wallet returns an error                       |

***

## Polling Strategy

Without webhooks, poll for changes at appropriate intervals:

| Data                | Endpoint                           | Interval | Reason                            |
| ------------------- | ---------------------------------- | -------- | --------------------------------- |
| Grant status        | `listGrants`                       | 5 min    | Vesting events happen on schedule |
| Wallet verification | `getPendingWalletRequests`         | 2 min    | Users may confirm quickly         |
| Wallet test txns    | `getTestTxnApprovalPendingWallets` | 2 min    | Time-sensitive approval           |
| Org configuration   | `getOrgWalletInfo`                 | 30 min   | Rarely changes                    |
| Networks/tokens     | `getNetworksNew`                   | 1 hour   | Rarely changes                    |

***

## External Employee ID

Always set `externalEmployeeID` when creating recipients. This is your primary key for correlating Toku data with your HRIS:

```typescript theme={null}
// Create with external ID
await tokuAPI('POST', 'createUserRoleInOrg', {
  email: 'jane@company.com',
  givenName: 'Jane',
  familyName: 'Smith',
  externalEmployeeID: 'EMP-001'  // Your system's ID
});

// Later, look up by external ID
const grants = await tokuAPI('GET',
  'getEmployeeGrants?externalEmployeeID=EMP-001'
);

// Terminate by external ID
await tokuAPI('POST', 'terminateEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  terminationDate: '2026-06-30T00:00:00.000Z'
});
```

***

## Multi-Organization

Each API token is scoped to **one organization**. If you manage multiple orgs, you need a separate token for each. Token scoping is enforced server-side — a token for Org A cannot access Org B's data.


# Build a Token Grant Dashboard
Source: https://docs.toku.com/api/guides/build-a-dashboard

End-to-end guide: integrate with Toku to build your own token grant management dashboard

## Overview

This guide walks you through building a complete token grant management integration with the Toku API. By the end, you'll have everything needed to:

* Onboard recipients and assign roles
* Create and manage token grants with vesting schedules
* Set up and verify recipient wallets
* Configure token distributions
* Handle terminations and reversals
* Monitor vesting progress

## Prerequisites

* A Toku organization with `CLIENT_ORG_ADMIN` access
* A [personal API token](/api/authentication)
* Your organization's `orgID` (found in **Settings** → **Organization ID**)

## Base Setup

Every request needs these headers:

```typescript theme={null}
const TOKU_BASE_URL = 'https://app.toku.com/api/tokuApi/v1';
const API_TOKEN = 'your-api-token-here';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'x-role-type': 'CLIENT_ORG_ADMIN',
  'Content-Type': 'application/json'
};

async function tokuAPI(method: string, endpoint: string, body?: any) {
  const res = await fetch(`${TOKU_BASE_URL}/${endpoint}`, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined
  });
  if (!res.ok) {
    const error = await res.json();
    throw new Error(`${res.status}: ${error.error} - ${error.details}`);
  }
  return res.json();
}
```

***

## Step 1: Verify Your Connection

```typescript theme={null}
const hello = await tokuAPI('GET', 'hello');
console.log(hello.message); // "Hello World"
```

```bash theme={null}
curl https://app.toku.com/api/tokuApi/v1/hello \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN"
```

***

## Step 2: Get Your Organization Info

```typescript theme={null}
const orgInfo = await tokuAPI('GET', 'getOrgWalletInfo');
console.log(orgInfo);
// {
//   orgID: "aa0e8400-...",
//   orgName: "Acme Corp",
//   isMfaEnabled: true,
//   automatedTestTransactionsEnabled: true,
//   tokenId: "ETH"
// }
```

***

## Step 3: Configure Networks & Tokens

Check what networks and tokens are available:

```typescript theme={null}
// Get configured networks
const { networks } = await tokuAPI('GET', 'getNetworksNew');
// [{ networkID: "...", name: "Ethereum", tokenTypes: [...] }]

// Get configured token types
const { tokenTypes } = await tokuAPI('GET', 'getTokenTypesNew');
// [{ tokenTypeID: "...", name: "USDC", currencyCode: "USDC" }]
```

If you need to set your token contract address:

```typescript theme={null}
await tokuAPI('POST', 'updateOrgTokenAddress', {
  orgID: 'your-org-id',
  tokenAddress: '0x1234...your-token-contract'
});
```

***

## Step 4: Add Recipients

Create users who will receive grants:

```typescript theme={null}
// Add a single recipient
const recipient = await tokuAPI('POST', 'createUserRoleInOrg', {
  email: 'jane.smith@company.com',
  givenName: 'Jane',
  familyName: 'Smith',
  externalEmployeeID: 'EMP-001',  // Your HRIS ID
  country: 'US',
  employmentType: 'FULL_TIME'
});

console.log(recipient.roleInOrgID);
// "660e8400-..." — save this, you'll need it for grants and wallets
```

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/createUserRoleInOrg \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@company.com",
    "givenName": "Jane",
    "familyName": "Smith",
    "externalEmployeeID": "EMP-001",
    "country": "US"
  }'
```

For bulk onboarding, use batch updates:

```typescript theme={null}
const result = await tokuAPI('PUT', 'batchUpdateRoleInOrg', {
  updates: [
    { employeeID: 'EMP-001', givenName: 'Jane', familyName: 'Smith' },
    { employeeID: 'EMP-002', givenName: 'Bob', familyName: 'Jones' }
  ]
});
// { updated: 2, failed: 0, results: [...] }
```

***

## Step 5: Get Grant Configurations

Before creating grants, you need a grant configuration (template):

```typescript theme={null}
const configs = await tokuAPI('GET', 'listGrantConfigurations');
// [{ grantConfigurationID: "...", grantConfigurationName: "Standard RTU" }]

const configID = configs[0].grantConfigurationID;
```

<Tip>
  Grant configurations define the grant type (RTU, RTA, TPA, TOKEN\_BONUS) and signing requirements. Create them in the [TGA dashboard](/tga/client/grant-configurations) first.
</Tip>

***

## Step 6: Create Grants

### Single Grant

```typescript theme={null}
const grant = await tokuAPI('POST', 'addSingleGrant', {
  grantName: 'Q1 2026 Token Grant - Jane Smith',
  grantConfigurationID: configID,
  grantAmount: 50000,
  recipientID: recipient.roleInOrgID,
  vestingStartDate: '2026-01-01T00:00:00.000Z',
  vestingFrequencyType: 'MONTHLY',
  vestingPeriods: 48,
  vestingCliffPeriods: 12,
  vestingCliffPercentage: 25,
  tags: ['engineering', '2026']
});

console.log(grant.grantID);
```

### New Hire Grant (creates user + grant in one call)

```typescript theme={null}
const newHireGrant = await tokuAPI('POST', 'createGrantForNewHire', {
  email: 'new.hire@company.com',
  givenName: 'New',
  familyName: 'Hire',
  employmentType: 'FULL_TIME',
  grantName: 'New Hire Grant',
  grantDescription: 'Signing bonus',
  grantConfigurationID: configID,
  grantAmount: 10000,
  vestingStartDate: '2026-04-01T00:00:00.000Z',
  vestingFrequencyType: 'MONTHLY',
  vestingPeriods: 48,
  vestingCliffPeriods: 12,
  vestingCliffPercentage: 25,
  lockup: 0,
  offPlatformDate: '2030-04-01T00:00:00.000Z',
  tags: ['new-hire']
});
```

***

## Step 7: Monitor Grants

### List all grants

```typescript theme={null}
const grants = await tokuAPI('GET', 'listGrants');

// Filter by status
const activeGrants = grants.filter(g => g.grantStatus === 'ACCEPTED');
const pendingGrants = grants.filter(g => g.grantStatus === 'PENDING');

// Filter by employee
const janeGrants = grants.filter(g => g.externalEmployeeID === 'EMP-001');
```

### Get grants for a specific employee

```typescript theme={null}
const employeeGrants = await tokuAPI('GET',
  'getEmployeeGrants?externalEmployeeID=EMP-001'
);
```

<Warning>
  List endpoints return **all** results (no pagination). For large organizations, cache results locally and poll periodically rather than calling on every page load.
</Warning>

***

## Step 8: Set Up Wallets

### Add a wallet for a recipient

```typescript theme={null}
const wallet = await tokuAPI('POST', 'addWallet', {
  name: 'Primary ETH Wallet',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  network: 'Ethereum',
  orgNetworkID: networks[0].networkID,
  tokenTypeID: tokenTypes[0].tokenTypeID
});
```

### Verify the wallet (test transaction flow)

```typescript theme={null}
// 1. Send a test transaction
await tokuAPI('POST', 'sendTestTransaction', {
  walletID: wallet.walletID
});

// 2. After recipient confirms receipt, approve the wallet
const pendingRequests = await tokuAPI('GET', 'getTestTxnApprovalPendingWallets');
for (const req of pendingRequests) {
  await tokuAPI('POST', 'approveWalletRequest', {
    walletRequestID: req.walletVerificationRequest?.walletRequestID
  });
}
```

### Bulk upload wallets

```typescript theme={null}
await tokuAPI('POST', 'bulkUploadMultipleWallets', {
  wallets: [
    {
      recipientID: 'role-in-org-uuid',
      walletAddress: '0xabc...',
      networkName: 'Ethereum',
      walletType: 'Hot Wallet'
    }
  ]
});
```

See [Wallet Verification Flow](/api/guides/wallet-verification-flow) for the complete state machine.

***

## Step 9: Configure Distributions

Set how tokens are distributed across a recipient's wallets:

```typescript theme={null}
await tokuAPI('POST', 'configureWalletRefsDistributionForGrant', {
  grantID: grant.grantID,
  roleInOrgID: recipient.roleInOrgID,
  walletRefsconfig: [
    { walletReferenceID: 'ref-uuid', distRatio: 1.0 }
  ]
});
```

Or set token-level distribution (applies to all grants):

```typescript theme={null}
await tokuAPI('POST', 'setTokenWalletRefsDistribution', {
  roleInOrgID: recipient.roleInOrgID,
  tokenWalletRefsConfig: [
    { walletID: wallet.walletID, distRatio: 0.7 },
    { walletID: secondWallet.walletID, distRatio: 0.3 }
  ]
});
```

***

## Step 10: Handle Terminations

### Terminate a single grant

```typescript theme={null}
await tokuAPI('POST', 'terminateGrant', {
  grantID: 'grant-uuid',
  terminationDate: '2026-06-30T00:00:00.000Z'
});
```

### Terminate all grants for a departing employee

```typescript theme={null}
const result = await tokuAPI('POST', 'terminateEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  terminationDate: '2026-06-30T00:00:00.000Z'
});
// { terminatedGrantIDs: [...], alreadyTerminatedGrantIDs: [...] }
```

### Revert a termination (mistake recovery)

```typescript theme={null}
await tokuAPI('POST', 'revertEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  grantIDs: ['grant-uuid-1', 'grant-uuid-2']
});
// { revertedGrantIDs: [...], alreadyActiveGrantIDs: [...] }
```

***

## Step 11: Polling for Status Changes

Since webhooks are not yet available, poll for changes:

```typescript theme={null}
// Poll grants every 5 minutes
async function pollGrants() {
  const grants = await tokuAPI('GET', 'listGrants');

  for (const grant of grants) {
    // Check for newly vested tokens
    if (grant.percentageOfUnitsVested > lastKnownPercentage[grant.grantID]) {
      console.log(`Grant ${grant.grantName}: ${grant.percentageOfUnitsVested}% vested`);
    }

    // Check for status changes
    if (grant.grantStatus !== lastKnownStatus[grant.grantID]) {
      console.log(`Grant ${grant.grantName}: status changed to ${grant.grantStatus}`);
    }
  }
}

setInterval(pollGrants, 5 * 60 * 1000);
```

***

## Complete Example: Onboard & Grant

```typescript theme={null}
async function onboardAndGrant(employee: {
  email: string;
  firstName: string;
  lastName: string;
  externalID: string;
  tokenAmount: number;
}) {
  // 1. Create the recipient
  const recipient = await tokuAPI('POST', 'createUserRoleInOrg', {
    email: employee.email,
    givenName: employee.firstName,
    familyName: employee.lastName,
    externalEmployeeID: employee.externalID,
    country: 'US'
  });

  // 2. Get grant config
  const configs = await tokuAPI('GET', 'listGrantConfigurations');
  const config = configs[0];

  // 3. Create the grant
  const grant = await tokuAPI('POST', 'addSingleGrant', {
    grantName: `${employee.firstName} ${employee.lastName} - Token Grant`,
    grantConfigurationID: config.grantConfigurationID,
    grantAmount: employee.tokenAmount,
    recipientID: recipient.roleInOrgID,
    vestingStartDate: new Date().toISOString(),
    vestingFrequencyType: 'MONTHLY',
    vestingPeriods: 48,
    vestingCliffPeriods: 12,
    vestingCliffPercentage: 25
  });

  return { recipientID: recipient.roleInOrgID, grantID: grant.grantID };
}
```

***

## Next Steps

<CardGroup>
  <Card title="Grant Lifecycle" icon="rotate" href="/api/guides/grant-lifecycle">
    Understand grant status transitions and edge cases
  </Card>

  <Card title="Wallet Verification" icon="shield-check" href="/api/guides/wallet-verification-flow">
    Complete wallet setup and verification flow
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/api/guides/best-practices">
    Rate limiting, caching, and error handling
  </Card>

  <Card title="Permissions" icon="lock" href="/api/guides/rbac-permissions">
    Role-based access control matrix
  </Card>
</CardGroup>


# Custody Setup Guide
Source: https://docs.toku.com/api/guides/custody-setup

Connect Fireblocks, Anchorage, or Safe for automated token settlement

## Overview

Before you can submit settlements via API, you need to connect a custody provider. This guide covers setup for all three supported providers.

***

## Fireblocks

<Steps>
  <Step title="Save integration credentials">
    ```typescript theme={null}
    await tokuAPI('POST', 'saveFireblocksIntegration', {
      fireblocksApiKey: 'your-fireblocks-api-key',
      fireblocksNetworkID: 'network-uuid'  // from getNetworksNew
    });
    ```

    This tests the connection before saving.
  </Step>

  <Step title="List vault accounts">
    ```typescript theme={null}
    const vaults = await tokuAPI('GET', 'getFireblocksVaultAccounts');
    // [{ vaultAccountId: "vault-123", vaultAccountName: "Main Vault" }]
    ```
  </Step>

  <Step title="Create or link a custody wallet">
    **Create new vault:**

    ```typescript theme={null}
    await tokuAPI('POST', 'createFireblocksCustodyWallet', {
      walletNames: ['Grant Vault 1', 'Grant Vault 2']
    });
    ```

    **Or link existing:**

    ```typescript theme={null}
    await tokuAPI('POST', 'linkExistingFireblocksCustodyWallet', {
      vaultAccountId: 'vault-123',
      vaultAccountName: 'Existing Vault'
    });
    ```
  </Step>

  <Step title="Allocate to grants">
    ```typescript theme={null}
    await tokuAPI('POST', 'addCustodyAllocationsToGrant', {
      allocations: [{
        walletAddress: '0xvault-address...',
        allocationAmount: 50000,
        grantID: 'grant-uuid'
      }]
    });
    ```
  </Step>
</Steps>

***

## Anchorage

<Steps>
  <Step title="Get your signer public key">
    ```typescript theme={null}
    const { publicKey } = await tokuAPI('GET', 'getAnchorageIntegrationPublicKey');
    // Register this key in your Anchorage account
    ```
  </Step>

  <Step title="Configure integration">
    ```typescript theme={null}
    await tokuAPI('POST', 'updateAnchorageIntegration', {
      anchorageDigitalApiKey: 'your-anchorage-api-key',
      anchorageDigitalGrantVaultID: 'vault-id',
      anchorageDigitalAssetType: 'ETH',
      anchorageNetworkID: 'network-uuid',
      anchorageDigitalIntegrationEnabled: true
    });
    ```
  </Step>

  <Step title="List vaults">
    ```typescript theme={null}
    const { vaults } = await tokuAPI('GET', 'getAnchorageVaults');
    // [{ vaultId: "vault-abc", name: "Primary Vault" }]
    ```
  </Step>

  <Step title="Create or link custody wallet">
    ```typescript theme={null}
    await tokuAPI('POST', 'createAnchorageCustodyWallet', {
      walletNames: ['Grant Wallet']
    });
    ```
  </Step>

  <Step title="Allocate to grants">
    Same as Fireblocks — use `addCustodyAllocationsToGrant`.
  </Step>
</Steps>

***

## Safe (Gnosis Multisig)

<Steps>
  <Step title="Check integration status">
    ```typescript theme={null}
    const safe = await tokuAPI('GET', 'getGnosisSafeIntegration');
    // { hasIntegration: true, signerPublicKey: "0x...", connectedSafeAddress: "0x..." }
    ```
  </Step>

  <Step title="Test Safe connection">
    ```typescript theme={null}
    await tokuAPI('POST', 'testGnosisSafeConnection', {
      safeAddress: '0xsafe-address...',
      chainId: '1'  // Ethereum mainnet
    });
    ```

    This verifies the Safe exists and Toku's proposer is registered as a delegate.
  </Step>

  <Step title="List Safe wallets">
    ```typescript theme={null}
    const { safeWallets } = await tokuAPI('GET', 'getSafeWallets');
    ```
  </Step>
</Steps>

***

## Managing Custody Wallets

### List all wallets

```typescript theme={null}
const wallets = await tokuAPI('GET', 'getAllCustodyWallets');
```

### Check wallet counts by provider

```typescript theme={null}
const { totalCount, countsByProvider } = await tokuAPI('GET', 'getCustodyWalletCount');
// { totalCount: 12, countsByProvider: { FIREBLOCKS: 5, ANCHORAGE: 4, SAFE: 3 } }
```

### Refresh balances

```typescript theme={null}
await tokuAPI('POST', 'bulkUpdateCustodyWalletBalance', {
  custodyWalletIDs: ['wallet-1', 'wallet-2']
});
```

### View allocations for a grant

```typescript theme={null}
const wallets = await tokuAPI('GET', 'getCustodyWalletsForGrant?grantID=grant-uuid');
```

### Update allocation amounts

```typescript theme={null}
await tokuAPI('POST', 'updateCustodyAllocations', {
  updates: [
    { custodyAllocationID: 'alloc-uuid', allocationAmount: 30000 }
  ]
});
```

### Remove allocations

```typescript theme={null}
await tokuAPI('POST', 'deleteCustodyAllocations', {
  custodyAllocationIDs: ['alloc-uuid-1', 'alloc-uuid-2']
});
```

***

## Removing an Integration

```typescript theme={null}
// Fireblocks
await tokuAPI('POST', 'deleteFireblocksIntegration');

// Anchorage
await tokuAPI('POST', 'deleteAnchorageIntegration');

// Safe
await tokuAPI('POST', 'deleteGnosisSafeIntegration');
```

***

## Next Steps

<CardGroup>
  <Card title="Distribution Workflow" icon="share-nodes" href="/api/guides/distribution-workflow">
    Submit settlements through your connected provider
  </Card>

  <Card title="Build a Dashboard" icon="code" href="/api/guides/build-a-dashboard">
    Complete integration guide
  </Card>
</CardGroup>


# Distribution Workflow
Source: https://docs.toku.com/api/guides/distribution-workflow

Step-by-step guide to process token distributions: approve, tax, settle

## Overview

When tokens vest, they go through a multi-step process before reaching the recipient's wallet. This guide walks through every step with API calls.

```mermaid theme={null}
graph TD
    A[Vesting Occurs] --> B[Approve Schedule]
    B --> C[Add Tax Details]
    C --> D[Update FMV if needed]
    D --> E[Finalize Tax]
    E --> F[Submit to Custody]
    F --> G[Track Settlement]
    G --> H[Record Completion]
```

***

## Step 1: Get Pending Schedules

Check what vestings need approval:

```typescript theme={null}
const { pendingSchedules } = await tokuAPI('GET',
  'getPendingSchedules?scheduleTypes=VESTING&lookaheadMonths=1'
);

for (const schedule of pendingSchedules) {
  console.log(`${schedule.recipientName}: ${schedule.units} tokens on ${schedule.vestDate}`);
}
```

***

## Step 2: Approve Schedules

Approve a batch of pending vestings:

```typescript theme={null}
const scheduleIDs = pendingSchedules.map(s => s.scheduleID);

await tokuAPI('POST', 'batchApproveSchedules', {
  scheduleIDs,
  scheduleType: 'VESTING',
  performanceFactor: 1.0  // 1.0 = 100% of scheduled amount
});
```

***

## Step 3: View Tax Grouping

Get approved schedules ready for tax details:

```typescript theme={null}
const { groupedSchedules } = await tokuAPI('GET',
  'getSchedulesAwaitingTaxGrouping?scheduleTypes=VESTING'
);
// Grouped by recipient for efficient tax processing
```

***

## Step 4: Add Tax Details

Choose one method per recipient group:

### Option A: No Tax (FMV tracking only)

```typescript theme={null}
await tokuAPI('POST', 'addNoTaxDetails', {
  scheduleIDs: ['schedule-uuid-1', 'schedule-uuid-2'],
  scheduleType: 'VESTING',
  taxCurrencyCode: 'USD',
  fmvPerUnit: 0.50  // Fair market value per token
});
```

### Option B: Manual Tax Withholding

```typescript theme={null}
await tokuAPI('POST', 'addManualTaxDetails', {
  scheduleIDs: ['schedule-uuid-1', 'schedule-uuid-2'],
  scheduleType: 'VESTING',
  taxCurrencyCode: 'USD',
  fmvPerUnit: 0.50,
  withholdingPercentage: 37  // 37% tax withholding
});
```

### Option C: Bulk Processing (mixed methods)

```typescript theme={null}
await tokuAPI('POST', 'bulkDistributionProcessing', {
  items: [
    { scheduleID: 'id-1', scheduleType: 'VESTING', taxMethod: 'NO_TAX', fmvPerUnit: 0.50, taxCurrencyCode: 'USD' },
    { scheduleID: 'id-2', scheduleType: 'VESTING', taxMethod: 'MANUAL_TAX', fmvPerUnit: 0.50, taxRate: 37, taxCurrencyCode: 'USD' }
  ]
});
```

***

## Step 5: Update FMV (Optional)

If the token price changed before finalization:

```typescript theme={null}
await tokuAPI('POST', 'batchUpdateFMV', {
  taxReferenceIDs: ['tax-ref-uuid-1', 'tax-ref-uuid-2'],
  scheduleType: 'VESTING',
  newFmv: 0.55  // Updated price
});
```

***

## Step 6: Finalize Tax Details

Move schedules to ready-for-settlement:

```typescript theme={null}
// Check what's awaiting finalization
const { taxFinalizationGroups } = await tokuAPI('GET',
  'getSchedulesAwaitingTaxFinalization?scheduleTypes=VESTING'
);

// Finalize
await tokuAPI('POST', 'batchFinalizeTaxDetails', {
  taxReferenceIDs: taxFinalizationGroups.map(g => g.taxReferenceID),
  scheduleType: 'VESTING'
});
```

To reject and send back to tax grouping:

```typescript theme={null}
await tokuAPI('POST', 'batchRejectTaxDetails', {
  taxReferenceIDs: ['tax-ref-uuid'],
  scheduleType: 'VESTING',
  reason: 'FMV needs update'
});
```

***

## Step 7: Submit to Custody

Check eligibility, then submit:

```typescript theme={null}
// Check if settlement can be submitted
const { allowed, reason } = await tokuAPI('GET',
  'canSubmitScheduleSettlement?taxReferenceID=tax-ref-uuid'
);

if (allowed) {
  // Submit to Fireblocks or Anchorage
  const { transactionID } = await tokuAPI('POST', 'submitScheduleSettlement', {
    taxReferenceID: 'tax-ref-uuid',
    providerName: 'FIREBLOCKS',  // or 'ANCHORAGE'
    custodyWalletID: 'wallet-uuid'  // optional: specific vault
  });
}
```

***

## Step 8: Track Settlement Status

```typescript theme={null}
const status = await tokuAPI('GET',
  'getScheduleSettlementStatus?taxReferenceID=tax-ref-uuid'
);

console.log(status);
// { hasTransaction: true, status: "PROCESSING", canSubmit: false, canRetry: false }
```

If it fails, retry:

```typescript theme={null}
if (status.canRetry) {
  await tokuAPI('POST', 'retryScheduleSettlement', {
    taxReferenceID: 'tax-ref-uuid'
  });
}
```

***

## Step 9: Record Completion

After on-chain confirmation:

```typescript theme={null}
await tokuAPI('POST', 'settleTaxReference', {
  taxReferenceID: 'tax-ref-uuid',
  scheduleType: 'VESTING',
  settlementDate: '2026-04-15T00:00:00.000Z',
  transactionHash: '0xabc123...',
  transactionLink: 'https://etherscan.io/tx/0xabc123...'
});
```

For batch recording:

```typescript theme={null}
await tokuAPI('POST', 'batchSettleSchedules', {
  scheduleType: 'VESTING',
  settlements: [
    { taxReferenceID: 'ref-1', settlementDate: '2026-04-15T00:00:00.000Z', transactionHash: '0x...' },
    { taxReferenceID: 'ref-2', settlementDate: '2026-04-15T00:00:00.000Z', transactionHash: '0x...' }
  ]
});
```

***

## Step 10: View Settlement History

```typescript theme={null}
const { settlements, total, hasMore } = await tokuAPI('GET',
  'getAllSettlementsForOrg?statusFilter=completed&page=1&pageSize=50'
);
```

***

## Error Recovery

### Revert tax details (send back to grouping)

```typescript theme={null}
await tokuAPI('POST', 'revertTaxDetails', {
  taxReferenceIDs: ['tax-ref-uuid'],
  scheduleType: 'VESTING'
});
```

### Revert schedule approval (send back to pending)

```typescript theme={null}
await tokuAPI('POST', 'revertScheduleApproval', {
  scheduleIDs: ['schedule-uuid'],
  scheduleType: 'VESTING'
});
```


# Grant Lifecycle
Source: https://docs.toku.com/api/guides/grant-lifecycle

Understand grant statuses, transitions, and edge cases

## Grant State Machine

Every grant moves through a defined set of statuses. Understanding these transitions is critical for building a reliable integration.

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING : Grant created
    PENDING --> ACCEPTED : Recipient accepts
    PENDING --> REJECTED : Recipient declines
    ACCEPTED --> COMPLETED : All vestings complete
    ACCEPTED --> TERMINATED : Admin terminates
    ACCEPTED --> PAUSED : Admin pauses
    ACCEPTED --> MARKED_FOR_FUTURE_TERMINATION : Future termination scheduled
    PAUSED --> ACCEPTED : Admin resumes
    TERMINATED --> ACCEPTED : Admin reverts termination
    MARKED_FOR_FUTURE_TERMINATION --> TERMINATED : Termination date reached
    MARKED_FOR_FUTURE_TERMINATION --> ACCEPTED : Admin reverts
```

## Status Reference

| Status                          | Meaning                                        | Can Transition To                                                    |
| ------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| `PENDING`                       | Grant created, waiting for recipient to accept | `ACCEPTED`, `REJECTED`                                               |
| `ACCEPTED`                      | Active and vesting                             | `COMPLETED`, `TERMINATED`, `PAUSED`, `MARKED_FOR_FUTURE_TERMINATION` |
| `REJECTED`                      | Recipient declined the grant                   | Terminal state                                                       |
| `COMPLETED`                     | All vesting periods finished                   | Terminal state                                                       |
| `TERMINATED`                    | Terminated early; future vestings cancelled    | `ACCEPTED` (via revert)                                              |
| `PAUSED`                        | Vesting temporarily suspended                  | `ACCEPTED` (via resume)                                              |
| `MARKED_FOR_FUTURE_TERMINATION` | Termination scheduled for a future date        | `TERMINATED`, `ACCEPTED` (via revert)                                |

***

## Creating a Grant

When you call [addSingleGrant](/api/grants/add-single-grant), the grant is created in `PENDING` status. The recipient receives an email notification.

```typescript theme={null}
const grant = await tokuAPI('POST', 'addSingleGrant', {
  grantName: 'Q1 Token Grant',
  grantConfigurationID: 'config-uuid',
  grantAmount: 50000,
  recipientID: 'role-in-org-uuid',
  vestingStartDate: '2026-01-01T00:00:00.000Z',
  vestingFrequencyType: 'MONTHLY',
  vestingPeriods: 48,
  vestingCliffPeriods: 12,
  vestingCliffPercentage: 25
});
// grant.grantID = "550e8400-..."
// Status: PENDING
```

***

## Vesting Calculation

Once a grant reaches `ACCEPTED`, vestings are calculated automatically:

### Standard 4-Year Schedule (48 months, 12-month cliff, 25% cliff)

| Event        | Month | Tokens       | Cumulative |
| ------------ | ----- | ------------ | ---------- |
| Grant starts | 0     | 0            | 0          |
| Cliff vests  | 12    | 12,500 (25%) | 12,500     |
| Monthly vest | 13    | \~1,042      | 13,542     |
| Monthly vest | 14    | \~1,042      | 14,583     |
| ...          | ...   | ...          | ...        |
| Fully vested | 48    | \~1,042      | 50,000     |

### Monitoring Vesting Progress

```typescript theme={null}
const grants = await tokuAPI('GET', 'listGrants');
for (const g of grants) {
  console.log(`${g.grantName}: ${g.percentageOfUnitsVested}% vested`);
  // "Q1 Token Grant: 16.67% vested"
}
```

The `percentageOfUnitsVested` field updates as vestings occur. Poll periodically to track progress.

***

## Termination

### Immediate Termination

Terminates the grant and recalculates vestings — only tokens vested before the termination date are retained.

```typescript theme={null}
await tokuAPI('POST', 'terminateGrant', {
  grantID: 'grant-uuid',
  terminationDate: '2026-06-30T00:00:00.000Z'
});
// Status: TERMINATED
```

### Future Termination

Set a termination date in the future. The grant remains active until that date.

```typescript theme={null}
await tokuAPI('POST', 'terminateGrant', {
  grantID: 'grant-uuid',
  terminationDate: '2026-12-31T00:00:00.000Z' // 6 months from now
});
// Status: MARKED_FOR_FUTURE_TERMINATION
```

### Bulk Termination (Employee Departure)

Terminate all grants when an employee leaves:

```typescript theme={null}
const result = await tokuAPI('POST', 'terminateEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  terminationDate: '2026-06-30T00:00:00.000Z'
  // grantIDs omitted = terminate ALL active grants
});
// { terminatedGrantIDs: ["..."], alreadyTerminatedGrantIDs: [] }
```

Or terminate specific grants only:

```typescript theme={null}
await tokuAPI('POST', 'terminateEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  terminationDate: '2026-06-30T00:00:00.000Z',
  grantIDs: ['specific-grant-uuid']
});
```

***

## Reverting a Termination

Made a mistake? Revert a termination to restore the grant and regenerate future vestings.

### Single Grant

```typescript theme={null}
await tokuAPI('POST', 'revertGrantTermination', {
  grantID: 'terminated-grant-uuid'
});
// Status returns to: ACCEPTED
```

### Bulk Revert

```typescript theme={null}
const result = await tokuAPI('POST', 'revertEmployeeGrants', {
  externalEmployeeID: 'EMP-001',
  grantIDs: ['grant-1', 'grant-2']
});
// { revertedGrantIDs: [...], alreadyActiveGrantIDs: [...] }
```

<Warning>
  Reverting a termination regenerates all future vestings from the original schedule. Any settlements or distributions that were already processed for the terminated vestings are not affected.
</Warning>

***

## Edge Cases

### Grant with zero token amount

Fiat-only grants have `grantAmount: 0`. The `grantAmountInFiat` field holds the fiat value.

### Multiple grants per employee

An employee can have multiple independent grants, each with its own vesting schedule. Use `externalEmployeeID` or `roleInOrgID` to find all grants for an employee.

### Terminated then reverted

When a grant is reverted, it returns to `ACCEPTED` with the original vesting schedule fully restored. The termination is as if it never happened.

### Future termination then reverted

A `MARKED_FOR_FUTURE_TERMINATION` grant can be reverted before the termination date arrives. It returns to `ACCEPTED` immediately.

***

## Polling Strategy

Since webhooks are not yet available, poll for status changes:

| What to Check              | Endpoint                                       | Recommended Interval |
| -------------------------- | ---------------------------------------------- | -------------------- |
| Grant status changes       | `listGrants`                                   | Every 5 minutes      |
| New vesting events         | `listGrants` (check `percentageOfUnitsVested`) | Every 15 minutes     |
| Wallet verification status | `getPendingWalletRequests`                     | Every 2 minutes      |


# Roles & Permissions
Source: https://docs.toku.com/api/guides/rbac-permissions

Which API endpoints each role can access

## Overview

Every API request includes an `x-role-type` header that determines what the caller can do. Your API token must belong to a user with the specified role in the organization.

There are three permission levels in the Toku API:

| Level                      | Base Class                 | Who Can Call                                 | Count              |
| -------------------------- | -------------------------- | -------------------------------------------- | ------------------ |
| **Any authenticated user** | `AuthorisedOperation`      | Any user with a valid token + org membership | 36 endpoints (61%) |
| **Admin only**             | `AdminOperation`           | `CLIENT_ORG_ADMIN` or equivalent admin role  | 28 endpoints (38%) |
| **Client Admin only**      | `TokuClientAdminOperation` | `CLIENT_ORG_ADMIN` specifically              | 4 endpoints        |

<Tip>
  **For 3rd party integrations, use `CLIENT_ORG_ADMIN`.** It has access to all 68 public endpoints. Other roles have more limited scope.
</Tip>

***

## Permissions by Endpoint

### Grants (Admin Required)

All grant write operations require admin access.

| Endpoint                         | Method | Permission                  |
| -------------------------------- | ------ | --------------------------- |
| `listGrants`                     | GET    | Admin                       |
| `listGrantConfigurations`        | GET    | Admin                       |
| `getEmployeeGrants`              | GET    | Admin                       |
| `getPayrollEmployeeID`           | GET    | Admin                       |
| `addSingleGrant`                 | POST   | Admin                       |
| `createGrantForNewHire`          | POST   | **CLIENT\_ORG\_ADMIN only** |
| `terminateGrant`                 | POST   | Admin                       |
| `terminateGrants`                | POST   | Admin                       |
| `terminateEmployeeGrants`        | POST   | Admin                       |
| `revertGrantTermination`         | POST   | Admin                       |
| `revertEmployeeGrantTermination` | POST   | Admin                       |
| `revertEmployeeGrants`           | POST   | Admin                       |

### Wallets (Mostly Any Authenticated User)

Most wallet operations are available to any authenticated user — this allows recipients to manage their own wallets.

| Endpoint                           | Method   | Permission |
| ---------------------------------- | -------- | ---------- |
| `getAllWallets`                    | GET      | Any user   |
| `getCurrentWallet`                 | GET      | Any user   |
| `getUserCurrentWallets`            | GET      | Any user   |
| `getHistoricalWallets`             | GET      | Any user   |
| `getAllHistoricalWallets`          | GET      | Any user   |
| `getAllWalletsForAllRecipients`    | GET      | Any user   |
| `getPendingWallets`                | GET      | Any user   |
| `getPendingWalletRequest`          | GET      | Any user   |
| `getTestTxnApprovalPendingWallets` | GET      | Any user   |
| `getOrgWalletInfo`                 | GET      | Any user   |
| `getEmployeeWallets`               | GET      | **Admin**  |
| `getEmployeeHistoricalWallets`     | GET      | **Admin**  |
| `getPendingWalletRequests`         | GET      | **Admin**  |
| `getVerifiedWalletTestRequests`    | GET      | **Admin**  |
| `getPendingWalletTestRequests`     | GET      | **Admin**  |
| `addWallet`                        | POST     | Any user   |
| `updateWallet`                     | POST/PUT | Any user   |
| `markWalletAsNotCurrent`           | POST     | Any user   |
| `reactivateWallet`                 | POST     | Any user   |
| `approveWallet`                    | POST     | Any user   |
| `rejectWallet`                     | POST     | Any user   |
| `approveWalletRequest`             | POST     | Any user   |
| `rejectWalletRequest`              | POST     | Any user   |
| `cancelWalletRequest`              | POST     | Any user   |
| `bulkUploadMultipleWallets`        | POST     | Any user   |
| `addTestTransaction`               | POST     | Any user   |
| `sendTestTransaction`              | POST     | Any user   |
| `addTestTxnToWallet`               | POST     | Any user   |
| `processBulkTestTransactions`      | POST     | Any user   |
| `resendTestTxnEmailToWalletOwner`  | POST     | Any user   |

### Wallet Distribution (Any Authenticated User)

| Endpoint                                  | Method | Permission |
| ----------------------------------------- | ------ | ---------- |
| `getAllWalletReferencesForAllGrants`      | GET    | Any user   |
| `getWalletReferencesWithNetworks`         | GET    | Any user   |
| `configureWalletRefsDistributionForGrant` | POST   | Any user   |
| `setTokenWalletRefsDistribution`          | POST   | Any user   |

### Employees (Admin Required)

| Endpoint               | Method | Permission |
| ---------------------- | ------ | ---------- |
| `getUserRoleInOrg`     | GET    | Admin      |
| `createUserRoleInOrg`  | POST   | Admin      |
| `updateUserRoleInOrg`  | PUT    | Admin      |
| `batchUpdateRoleInOrg` | PUT    | Admin      |

### Tokens & Networks

| Endpoint           | Method | Permission |
| ------------------ | ------ | ---------- |
| `getWalletTypes`   | GET    | Any user   |
| `getTokenTypes`    | GET    | Any user   |
| `getTokenTypesNew` | GET    | Any user   |
| `getNetworks`      | GET    | Any user   |
| `getNetworksNew`   | GET    | Any user   |
| `deleteWalletType` | DELETE | **Admin**  |
| `deleteNetwork`    | DELETE | **Admin**  |

### Invoices (Admin Required)

| Endpoint                      | Method | Permission |
| ----------------------------- | ------ | ---------- |
| `submitBulkInvoicePayments`   | POST   | Admin      |
| `markInvoicePaymentAsSettled` | POST   | Admin      |

### Organization

| Endpoint                             | Method | Permission                  |
| ------------------------------------ | ------ | --------------------------- |
| `hello`                              | GET    | **CLIENT\_ORG\_ADMIN only** |
| `getOrgWalletInfo`                   | GET    | Any user                    |
| `updateOrgTokenAddress`              | POST   | Admin                       |
| `updateTestTransactionConfiguration` | PUT    | Admin                       |

### Authentication (CLIENT\_ORG\_ADMIN Only)

| Endpoint              | Method | Permission                  |
| --------------------- | ------ | --------------------------- |
| `createUserApiToken`  | POST   | **CLIENT\_ORG\_ADMIN only** |
| `refreshUserApiToken` | POST   | **CLIENT\_ORG\_ADMIN only** |
| `generateAuthNonce`   | POST   | Any user                    |

***

## Permission Levels Explained

### Any Authenticated User (`AuthorisedOperation`)

Requires a valid API token and membership in the organization. Any role works — `CLIENT_ORG_ADMIN`, `PAYROLL_ADMIN`, `FINANCE_ADMIN`, `INVESTOR`, or `RECIPIENT`.

### Admin (`AdminOperation`)

Requires `CLIENT_ORG_ADMIN` or another admin-level role (`PAYROLL_ADMIN` for some operations). The exact admin roles accepted vary by endpoint, but `CLIENT_ORG_ADMIN` always works.

### CLIENT\_ORG\_ADMIN Only (`TokuClientAdminOperation`)

Strictly requires the `CLIENT_ORG_ADMIN` role. No other admin role is accepted.

***

## Error When Permission Denied

```json theme={null}
{
  "error": "Invalid token or insufficient permissions",
  "details": "User does not have role CLIENT_ORG_ADMIN in organization aa0e8400-..."
}
```

**Status code:** `403 Forbidden` (role mismatch) or `401 Unauthorized` (invalid token)

***

## Recommendation

For a complete 3rd party integration that manages grants, wallets, and employees, create your API token with **`CLIENT_ORG_ADMIN`**. This is the only role guaranteed to work with all 68 public endpoints.


# Wallet Verification Flow
Source: https://docs.toku.com/api/guides/wallet-verification-flow

Step-by-step guide to adding, verifying, and approving recipient wallets

## Overview

Before tokens can be distributed, each recipient's wallet must be verified. Verification uses test transactions to confirm the recipient controls the wallet address.

## Wallet State Machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING : addWallet
    PENDING --> TEST_SENT : sendTestTransaction
    TEST_SENT --> VERIFIED : Recipient confirms
    VERIFIED --> CURRENT : approveWalletRequest
    CURRENT --> ARCHIVED : markWalletAsNotCurrent
    ARCHIVED --> CURRENT : reactivateWallet
    PENDING --> REJECTED : rejectWallet
    PENDING --> CANCELLED : cancelWalletRequest
```

***

## Step 1: Add a Wallet

```typescript theme={null}
const wallet = await tokuAPI('POST', 'addWallet', {
  name: 'Primary ETH Wallet',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  network: 'Ethereum',
  orgNetworkID: 'network-uuid',    // from getNetworksNew
  tokenTypeID: 'token-type-uuid'   // from getTokenTypesNew
});
// Returns: { walletID: "..." }
```

## Step 2: Send Test Transaction

Triggers a small token transfer to the wallet address:

```typescript theme={null}
await tokuAPI('POST', 'sendTestTransaction', {
  walletID: wallet.walletID
});
```

The system sends a configurable amount of tokens. The recipient receives an email notification with a link to confirm.

## Step 3: Recipient Confirms Receipt

The recipient logs into TGA and confirms they received the test amount. From the API side, you can check the status:

```typescript theme={null}
// Check for wallets pending approval
const pending = await tokuAPI('GET', 'getTestTxnApprovalPendingWallets');
```

## Step 4: Approve the Wallet

Once the recipient confirms, approve the wallet:

```typescript theme={null}
await tokuAPI('POST', 'approveWalletRequest', {
  walletRequestID: 'request-uuid',
  verifiedAmount: '0.001'  // optional: amount the recipient confirmed
});
// Wallet status → CURRENT (active for distributions)
```

***

## Bulk Verification

For multiple wallets at once:

```typescript theme={null}
// 1. Bulk upload wallets
await tokuAPI('POST', 'bulkUploadMultipleWallets', {
  wallets: [
    { recipientID: 'role-1', walletAddress: '0xabc...', networkName: 'Ethereum', walletType: 'Hot Wallet' },
    { recipientID: 'role-2', walletAddress: '0xdef...', networkName: 'Ethereum', walletType: 'Hot Wallet' }
  ]
});

// 2. Send test transactions in bulk
await tokuAPI('POST', 'processBulkTestTransactions', {
  walletIDs: ['wallet-1', 'wallet-2'],
  walletNetworkName: 'Ethereum'
});
```

***

## Handling Rejections

If a wallet fails verification:

```typescript theme={null}
// Reject the wallet
await tokuAPI('POST', 'rejectWalletRequest', {
  walletRequestID: 'request-uuid'
});
// Status → REJECTED
```

The recipient can then submit a new wallet address and restart the verification process.

***

## Deactivating & Reactivating Wallets

```typescript theme={null}
// Deactivate (move to historical)
await tokuAPI('POST', 'markWalletAsNotCurrent', {
  walletID: 'wallet-uuid'
});
// Status → ARCHIVED

// Reactivate
await tokuAPI('POST', 'reactivateWallet', {
  walletID: 'wallet-uuid'
});
// Status → CURRENT
```

***

## Querying Wallet Status

| Endpoint                           | Returns                                                  |
| ---------------------------------- | -------------------------------------------------------- |
| `getAllWallets`                    | All wallets across all recipients                        |
| `getEmployeeWallets`               | Current wallets for one employee                         |
| `getEmployeeHistoricalWallets`     | Archived wallets for one employee                        |
| `getPendingWallets`                | Wallets awaiting verification                            |
| `getPendingWalletRequests`         | All pending wallet requests                              |
| `getTestTxnApprovalPendingWallets` | Wallets with confirmed test txns awaiting admin approval |
| `getVerifiedWalletTestRequests`    | Verified wallet requests                                 |
| `getPendingWalletTestRequests`     | Unconfirmed test transactions                            |

***

## Resending Test Transaction Email

If a recipient didn't receive the notification:

```typescript theme={null}
await tokuAPI('POST', 'resendTestTxnEmailToWalletOwner', {
  walletID: 'wallet-uuid'
});
```


# API Overview
Source: https://docs.toku.com/api/overview

Build on the Toku platform with our REST API. Manage grants, wallets, employees, invoices, and more.

## Introduction

The Toku API lets you programmatically manage token grants, wallets, employees, payroll, and invoices. Everything you can do in the Toku dashboard is available via API, enabling you to build custom integrations and automate your token compensation workflows.

## Base URL

All API requests are made to:

```
https://app.toku.com/api/tokuApi/v1/{operationName}
```

## Request Format

* **GET** requests pass parameters as query strings
* **POST / PUT / DELETE** requests send JSON in the request body
* All responses return JSON

```bash theme={null}
# GET request example
curl https://app.toku.com/api/tokuApi/v1/listGrants \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN"

# POST request example
curl -X POST https://app.toku.com/api/tokuApi/v1/addSingleGrant \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{"grantName": "Q1 Token Grant", "grantAmount": 10000}'
```

## Required Headers

Every authenticated request must include:

| Header          | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| `Authorization` | `Bearer YOUR_API_TOKEN` — your personal API token                               |
| `x-role-type`   | The role to act as (e.g., `CLIENT_ORG_ADMIN`, `PAYROLL_ADMIN`, `FINANCE_ADMIN`) |
| `Content-Type`  | `application/json` (for POST/PUT/DELETE requests)                               |

## API Domains

<CardGroup>
  <Card title="Grants" icon="award" href="/api/grants">
    Create, list, terminate, and revert token grants
  </Card>

  <Card title="Wallets" icon="wallet" href="/api/wallets">
    Manage recipient wallets, test transactions, and distributions
  </Card>

  <Card title="Employees" icon="users" href="/api/employees">
    Create and manage user roles within your organization
  </Card>

  <Card title="Invoices" icon="file-invoice-dollar" href="/api/invoices">
    Submit and settle invoice payments
  </Card>

  <Card title="Organization" icon="building" href="/api/organization">
    Configure organization settings and token addresses
  </Card>

  <Card title="Webhooks" icon="bell" href="/api/webhooks">
    Receive real-time notifications for events
  </Card>
</CardGroup>

## Rate Limits

The API is rate-limited to **100 requests per minute** per IP address. If you exceed this limit, you'll receive a `429 Too Many Requests` response.

## Versioning

The current API version is **v1**. All endpoints are prefixed with `/api/tokuApi/v1/`.


# Create API Token
Source: https://docs.toku.com/api/protected-links/create-api-token

Create an API token for authenticated Toku API access.

# Create API Token

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fapi%2Fendpoints%2Fauthentication%2Fcreate-api-token">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# Generate Auth Nonce
Source: https://docs.toku.com/api/protected-links/generate-auth-nonce

Generate an authentication nonce for secure API authentication.

# Generate Auth Nonce

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fapi%2Fendpoints%2Fauthentication%2Fgenerate-auth-nonce">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# Refresh API Token
Source: https://docs.toku.com/api/protected-links/refresh-api-token

Refresh an existing API token for continued API access.

# Refresh API Token

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fapi%2Fendpoints%2Fauthentication%2Frefresh-api-token">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# Quick Start
Source: https://docs.toku.com/api/quickstart

Make your first Toku API call in under 5 minutes

## Prerequisites

* A Toku account with `CLIENT_ORG_ADMIN` access
* A personal API token (see [Authentication](/api/authentication))

## Your First API Call

Verify your token works by calling the hello endpoint:

```bash theme={null}
curl https://app.toku.com/api/tokuApi/v1/hello \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN"
```

Response:

```json theme={null}
{
  "message": "Hello World"
}
```

## List Your Grants

Retrieve all grants in your organization:

```bash theme={null}
curl https://app.toku.com/api/tokuApi/v1/listGrants \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN"
```

Response:

```json theme={null}
[
  {
    "grantID": "550e8400-e29b-41d4-a716-446655440000",
    "grantName": "Q1 2026 Token Grant",
    "grantAmount": 50000,
    "grantStatus": "ACCEPTED",
    "grantAmountInFiat": 25000,
    "grantConfigurationName": "Standard Vesting",
    "vestingStartDate": "2026-01-01T00:00:00.000Z",
    "vestingPeriods": 48,
    "vestingFrequencyType": "MONTHLY",
    "vestingCliffPeriods": 12,
    "vestingCliffPercentage": 25,
    "percentageOfUnitsVested": 16.67,
    "recipientFullName": "Jane Smith",
    "grantDate": "2025-12-15T00:00:00.000Z",
    "tags": ["engineering", "2026"],
    "roleInOrgID": "660e8400-e29b-41d4-a716-446655440001",
    "roleInOrgExternalID": 12345
  }
]
```

## Create a Grant

Add a new token grant for an employee:

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/addSingleGrant \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "grantName": "New Hire Grant",
    "grantConfigurationID": "YOUR_GRANT_CONFIG_ID",
    "grantAmount": 10000,
    "vestingStartDate": "2026-04-01T00:00:00.000Z",
    "vestingFrequencyType": "MONTHLY",
    "vestingPeriods": 48,
    "vestingCliffPeriods": 12,
    "vestingCliffPercentage": 25,
    "recipientID": "ROLE_IN_ORG_ID",
    "tags": ["new-hire", "2026"]
  }'
```

## Common Workflows

<CardGroup>
  <Card title="Grant Lifecycle" icon="rotate" href="/api/grants">
    Create grants, manage vesting, handle terminations
  </Card>

  <Card title="Wallet Setup" icon="wallet" href="/api/wallets">
    Add wallets, verify with test transactions, configure distributions
  </Card>

  <Card title="Employee Management" icon="users" href="/api/employees">
    Onboard employees, assign roles, sync from HRIS
  </Card>

  <Card title="Invoice Processing" icon="file-invoice-dollar" href="/api/invoices">
    Submit and settle contractor invoices
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Explore the API reference">
    Browse the full [Grants API](/api/grants), [Wallets API](/api/wallets), and [Employees API](/api/employees)
  </Step>

  <Step title="Set up webhooks">
    Configure [webhook endpoints](/api/webhooks) to receive real-time event notifications
  </Step>

  <Step title="Handle errors">
    Review [error codes](/api/errors) and implement proper error handling
  </Step>
</Steps>


# Compliance Basics
Source: https://docs.toku.com/contractor/client/compliance-basics

Understanding contractor compliance and classification

## Overview

Properly classifying and managing contractors is essential for compliance. Toku helps you maintain compliant contractor relationships across jurisdictions.

***

## Contractor vs Employee

Misclassifying employees as contractors can result in significant penalties. Key factors that distinguish contractors:

| Factor          | Contractor                            | Employee                                    |
| --------------- | ------------------------------------- | ------------------------------------------- |
| **Control**     | Works independently, sets own methods | Company controls how work is done           |
| **Tools**       | Uses own tools and equipment          | Company provides tools                      |
| **Exclusivity** | May work for multiple clients         | Typically works exclusively for one company |
| **Schedule**    | Sets own hours                        | Company sets schedule                       |
| **Risk**        | Bears financial risk                  | Company bears risk                          |

***

## Classification Guidance

Toku provides classification guidance based on:

* Contractor's country
* Nature of the engagement
* Responses to classification questionnaire

<Warning>
  Classification rules vary by country. When in doubt, consult with legal counsel in the contractor's jurisdiction.
</Warning>

***

## Compliance Requirements by Region

### United States

* Form W-9 collection
* 1099 reporting for payments over \$600
* State-specific requirements may apply

### European Union

* VAT considerations
* A1 certificates for EU nationals working across borders
* Country-specific contractor regulations

### Asia Pacific

* Withholding requirements vary by country
* Local entity may be required in some cases
* Tax treaty considerations

### Latin America

* Invoice requirements vary
* Withholding may be required
* Local compliance varies significantly

***

## Documentation

Toku collects and stores required documentation:

| Document            | Purpose                      |
| ------------------- | ---------------------------- |
| **Contract**        | Defines the engagement terms |
| **Tax Forms**       | W-9, VAT registration, etc.  |
| **ID Verification** | Confirms contractor identity |
| **Payment Info**    | Bank or payment details      |

***

## Tax Withholding

Some jurisdictions require tax withholding on contractor payments:

* Toku calculates applicable withholding
* Withheld amounts are remitted to tax authorities
* Contractors receive net payment after withholding

### Where Withholding Applies

* Certain US states
* Some Latin American countries
* Specific situations based on tax treaties

***

## Best Practices

<CardGroup>
  <Card title="Written Contracts" icon="file-signature">
    Always have a signed contractor agreement defining scope, terms, and relationship.
  </Card>

  <Card title="Regular Review" icon="magnifying-glass">
    Periodically review long-term contractors to ensure classification remains appropriate.
  </Card>

  <Card title="Documentation" icon="folder-open">
    Maintain complete records of contracts, invoices, and payments.
  </Card>

  <Card title="Consistent Treatment" icon="scale-balanced">
    Apply consistent policies across contractors to avoid classification issues.
  </Card>
</CardGroup>

***

## When to Consider Employee Status

Consider converting a contractor to an employee if:

* The engagement is ongoing and indefinite
* You're directing how they perform their work
* They work exclusively for your company
* Local laws require employee status

<Card title="Contractor FAQ" icon="circle-question" href="/contractor/faq">
  More questions about contractor compliance
</Card>

***

<Tip>
  **Contractor Client Guide** — Step 4 of 4. [Previous: Payments & Invoicing](/contractor/client/payments-and-invoicing)
</Tip>


# Managing Contractors
Source: https://docs.toku.com/contractor/client/managing-contractors

Manage contractor relationships and engagements

## Overview

Once contractors are onboarded, use Toku to manage their engagements, update terms, and maintain contractor records.

***

## Contractor Dashboard

View all your contractors in one place:

* **Active** — Currently engaged contractors
* **Pending** — Invited but not yet completed onboarding
* **Ended** — Past engagements

### Contractor Profile

Each contractor profile shows:

* Contact information
* Engagement details and terms
* Contract documents
* Invoice history
* Payment history

***

## Updating Engagement Terms

<Steps>
  <Step title="Navigate to contractor profile">
    Click on the contractor's name in your list
  </Step>

  <Step title="Click Edit Engagement">
    Select **Edit** next to Engagement Details
  </Step>

  <Step title="Update terms">
    Modify rate, payment frequency, or other terms
  </Step>

  <Step title="Generate amendment">
    If required, generate a contract amendment
  </Step>

  <Step title="Get contractor signature">
    Contractor signs the amendment electronically
  </Step>
</Steps>

***

## Common Actions

### Extend Engagement

To continue working with a contractor past their original end date:

1. Go to contractor profile
2. Click **Extend Engagement**
3. Set new end date
4. Confirm

### Change Payment Method

Contractors can update their payment method in their portal, or you can request a change:

1. Go to contractor profile
2. Click **Request Payment Update**
3. Contractor receives notification to update their details

### Put on Hold

Temporarily pause an engagement:

1. Go to contractor profile
2. Click **Actions** > **Put on Hold**
3. Select hold reason
4. Contractor is notified

***

## Ending Engagements

When a contractor engagement ends:

<Steps>
  <Step title="Process final invoice">
    Ensure all outstanding work is invoiced and paid
  </Step>

  <Step title="Navigate to contractor profile">
    Go to the contractor's profile
  </Step>

  <Step title="Click End Engagement">
    Select **Actions** > **End Engagement**
  </Step>

  <Step title="Set end date">
    Confirm the last day of the engagement
  </Step>

  <Step title="Confirm termination">
    The contractor is moved to "Ended" status
  </Step>
</Steps>

***

## Contractor Status

| Status      | Description                                 |
| ----------- | ------------------------------------------- |
| **Pending** | Invitation sent, awaiting contractor action |
| **Active**  | Engagement is active                        |
| **On Hold** | Temporarily paused                          |
| **Ended**   | Engagement has concluded                    |

***

## Re-engaging a Contractor

To work with a past contractor again:

1. Find them in the "Ended" list
2. Click **Re-engage**
3. Set up new engagement terms
4. Send new contract for signature

***

## Contractor Communication

### In-App Messaging

Send messages to contractors directly through Toku.

### Notifications

Contractors receive notifications for:

* Invoice approvals
* Payment processing
* Contract updates
* Rate changes

***

<Tip>
  **Contractor Client Guide** — Step 2 of 4. [Previous: Onboarding Contractors](/contractor/client/onboarding-contractors) | [Next: Payments & Invoicing](/contractor/client/payments-and-invoicing)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Payments & Invoicing" icon="money-bill-wave" href="/contractor/client/payments-and-invoicing">
    Process payments
  </Card>

  <Card title="Compliance" icon="shield-check" href="/contractor/client/compliance-basics">
    Understand compliance requirements
  </Card>
</CardGroup>


# Onboarding Contractors
Source: https://docs.toku.com/contractor/client/onboarding-contractors

Add and onboard contractors to your organization

## Overview

Toku Contractor simplifies global contractor onboarding with compliant contracts, automated workflows, and built-in verification.

***

## Adding a Contractor

<Steps>
  <Step title="Navigate to Contractors">
    Click **Contractors** in the sidebar
  </Step>

  <Step title="Click Add Contractor">
    Select **Add Contractor** to start the onboarding process
  </Step>

  <Step title="Enter contractor details">
    Fill in the contractor's information:

    * Full legal name
    * Email address
    * Country of residence
    * Engagement type (hourly, fixed, retainer)
  </Step>

  <Step title="Configure engagement terms">
    Set up the engagement:

    * Start date
    * Rate (hourly, daily, or fixed)
    * Payment frequency
    * Payment method preference
  </Step>

  <Step title="Generate contract">
    Review and customize the contractor agreement
  </Step>

  <Step title="Send invitation">
    Send the invitation to the contractor to complete onboarding
  </Step>
</Steps>

***

## Contractor Information Required

| Field        | Required | Description                                 |
| ------------ | -------- | ------------------------------------------- |
| Legal Name   | Yes      | Full legal name as it appears on ID         |
| Email        | Yes      | Primary contact email                       |
| Country      | Yes      | Country of residence/tax residence          |
| Address      | Yes      | Full address for compliance                 |
| Tax ID       | Varies   | Required in some jurisdictions              |
| Bank Details | Later    | Collected from contractor during onboarding |

***

## Engagement Types

### Hourly

Contractor bills based on hours worked. Best for ongoing work with variable hours.

### Fixed/Project-Based

Set fee for a defined scope of work. Best for discrete projects with clear deliverables.

### Retainer

Recurring monthly fee for ongoing availability. Best for advisory or on-call arrangements.

***

## Contract Generation

Toku generates compliant contractor agreements based on:

* Contractor's country
* Engagement type
* Your organization's preferences

### Customizing Contracts

You can customize:

* Scope of work description
* Confidentiality clauses
* IP assignment terms
* Termination provisions

### Electronic Signature

Contracts are signed electronically by both parties and stored securely in Toku.

***

## Contractor Onboarding Flow

After you send the invitation, the contractor:

1. Receives invitation email
2. Creates their Toku account
3. Reviews and signs the contract
4. Provides payment information
5. Completes any required verification
6. Is marked as "Active" in your system

***

## Bulk Onboarding

Onboard multiple contractors at once:

1. Navigate to **Contractors** > **Import**
2. Download the CSV template
3. Fill in contractor details
4. Upload the completed file
5. Review and confirm

***

<Tip>
  **Contractor Client Guide** — Step 1 of 4. [Next: Managing Contractors](/contractor/client/managing-contractors)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Manage Contractors" icon="users-gear" href="/contractor/client/managing-contractors">
    Manage active contractors
  </Card>

  <Card title="Payments & Invoicing" icon="money-bill-wave" href="/contractor/client/payments-and-invoicing">
    Process contractor payments
  </Card>
</CardGroup>


# Payments & Invoicing
Source: https://docs.toku.com/contractor/client/payments-and-invoicing

Process contractor invoices and payments

## Overview

Toku Contractor handles the full invoicing and payment workflow, from contractor submission through approval and payment.

***

## Invoice Workflow

<Steps>
  <Step title="Contractor submits invoice">
    Contractor creates and submits an invoice in their portal
  </Step>

  <Step title="Admin reviews">
    Review the invoice details, hours, and amounts
  </Step>

  <Step title="Approve or request changes">
    Approve the invoice or send back for revisions
  </Step>

  <Step title="Schedule payment">
    Approved invoices are queued for payment
  </Step>

  <Step title="Process payment">
    Payment is sent via the contractor's preferred method
  </Step>
</Steps>

***

## Reviewing Invoices

Navigate to **Payments** > **Invoices** to see:

* **Pending Review** — Invoices awaiting your approval
* **Approved** — Invoices approved and pending payment
* **Paid** — Completed payments
* **Rejected** — Invoices sent back for revision

### Invoice Details

Each invoice shows:

* Contractor name
* Invoice period/date
* Description of work
* Hours (if hourly)
* Total amount
* Any attached documentation

***

## Approving Invoices

<Steps>
  <Step title="Review the invoice">
    Verify hours, rate, and description match expectations
  </Step>

  <Step title="Check supporting documents">
    Review any attached time logs or deliverables
  </Step>

  <Step title="Click Approve">
    Approve the invoice for payment
  </Step>
</Steps>

### Requesting Changes

If an invoice needs revision:

1. Click **Request Changes**
2. Add a note explaining what needs to be corrected
3. The contractor receives notification to revise and resubmit

***

## Payment Processing

### Payment Methods

| Method        | Processing Time   | Fees                 |
| ------------- | ----------------- | -------------------- |
| Bank Transfer | 2-5 business days | Varies by country    |
| PayPal        | 1-2 business days | Standard PayPal fees |
| Crypto        | Same day          | Network fees         |
| Stablecoin    | Same day          | Network fees         |

### Payment Schedule

Configure your payment schedule:

* **Weekly** — All approved invoices paid weekly
* **Bi-weekly** — Payments every two weeks
* **Monthly** — End-of-month payments
* **On Approval** — Payment immediately upon approval

***

## Batch Payments

Process multiple invoices at once:

1. Go to **Payments** > **Invoices**
2. Select multiple approved invoices
3. Click **Process Batch Payment**
4. Review totals by payment method
5. Confirm to process

***

## Payment Status

| Status               | Description                         |
| -------------------- | ----------------------------------- |
| **Pending Approval** | Invoice submitted, awaiting review  |
| **Approved**         | Approved, queued for payment        |
| **Processing**       | Payment in progress                 |
| **Paid**             | Payment completed                   |
| **Failed**           | Payment failed — requires attention |

***

## Payment Receipts

Both you and the contractor receive payment confirmations:

* Email notification when payment is sent
* Receipt available in payment history
* Transaction details for record-keeping

***

<Tip>
  **Contractor Client Guide** — Step 3 of 4. [Previous: Managing Contractors](/contractor/client/managing-contractors) | [Next: Compliance Basics](/contractor/client/compliance-basics)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Compliance" icon="shield-check" href="/contractor/client/compliance-basics">
    Understand compliance requirements
  </Card>

  <Card title="Contractor FAQ" icon="circle-question" href="/contractor/faq">
    Common questions
  </Card>
</CardGroup>


# Contractor FAQ
Source: https://docs.toku.com/contractor/faq

Frequently asked questions about Toku Contractor

## For Contractors

<AccordionGroup>
  <Accordion title="How do I get started?">
    Accept the invitation email from your client, create your account, sign the contractor agreement, and add your payment information. You'll then be ready to submit invoices.
  </Accordion>

  <Accordion title="How do I submit an invoice?">
    Go to **Invoices**, click **Create Invoice**, fill in the details (period, description, hours if applicable), attach any supporting documents, and submit.
  </Accordion>

  <Accordion title="When will I get paid?">
    Payment timing depends on your client's payment schedule (weekly, bi-weekly, monthly, or on approval). Once your invoice is approved, payment is processed according to that schedule.
  </Accordion>

  <Accordion title="What payment methods are available?">
    You can receive payments via bank transfer, PayPal, cryptocurrency, or stablecoins. Set up your preferred method in **Settings** > **Payment Methods**.
  </Accordion>

  <Accordion title="How long do payments take?">
    Bank transfers take 2-5 business days. PayPal takes 1-2 days. Crypto and stablecoin payments are typically same-day.
  </Accordion>

  <Accordion title="Why was my invoice rejected?">
    Your client may request changes if there are issues with the invoice details, hours, or supporting documentation. Check their feedback, make corrections, and resubmit.
  </Accordion>

  <Accordion title="How do I update my payment information?">
    Go to **Settings** > **Payment Methods** to add or update your payment details.
  </Accordion>

  <Accordion title="Will I receive tax documents?">
    Yes. US contractors receiving \$600+ will receive a 1099. All contractors can access payment summaries and invoice history for tax purposes.
  </Accordion>

  <Accordion title="Can I work with multiple clients?">
    Yes. If multiple clients use Toku, you'll see all engagements in your dashboard and can invoice each separately.
  </Accordion>
</AccordionGroup>

***

## For Clients (Administrators)

<AccordionGroup>
  <Accordion title="How do I add a contractor?">
    Go to **Contractors**, click **Add Contractor**, enter their details, configure the engagement terms, and send the invitation.
  </Accordion>

  <Accordion title="How do I approve invoices?">
    Navigate to **Payments** > **Invoices** to see pending invoices. Review the details and click **Approve** or **Request Changes**.
  </Accordion>

  <Accordion title="What payment methods can we offer?">
    Toku supports bank transfers, PayPal, cryptocurrency, and stablecoin payments. Contractors choose their preferred method.
  </Accordion>

  <Accordion title="How do I end an engagement?">
    Go to the contractor's profile, process any final invoices, then click **Actions** > **End Engagement** and set the end date.
  </Accordion>

  <Accordion title="Can I bulk import contractors?">
    Yes. Go to **Contractors** > **Import**, download the CSV template, fill it out, and upload to onboard multiple contractors at once.
  </Accordion>

  <Accordion title="How do I handle contractor compliance?">
    Toku provides contractor classification guidance and collects required documentation. Review the Compliance section for best practices.
  </Accordion>

  <Accordion title="What happens if a contractor is in a country we haven't worked with before?">
    Toku supports contractors in 150+ countries. The system will guide you through any country-specific requirements during onboarding.
  </Accordion>

  <Accordion title="How do I set up approval workflows?">
    Configure invoice approval settings in **Settings** > **Approvals**. You can require single or multiple approvers for invoices above certain thresholds.
  </Accordion>
</AccordionGroup>

***

## General

<AccordionGroup>
  <Accordion title="Is my information secure?">
    Yes. Toku uses enterprise-grade security including encryption, secure data storage, and access controls.
  </Accordion>

  <Accordion title="What currencies are supported?">
    Toku supports payments in USD, EUR, GBP, and many other currencies, plus cryptocurrencies and stablecoins.
  </Accordion>

  <Accordion title="How do I contact support?">
    Email [support@toku.com](mailto:support@toku.com) or visit the Support page for help.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

<Card title="Contact Support" icon="headset" href="/getting-started/support">
  Get in touch with our team
</Card>


# Toku Contractor
Source: https://docs.toku.com/contractor/overview

Onboard and pay global contractors instantly

## What is Toku Contractor?

Toku Contractor is the platform for managing global contractor relationships. It helps organizations:

* Onboard contractors in 150+ countries
* Manage contracts and compliance
* Process payments in multiple currencies
* Handle invoicing and approvals
* Maintain contractor records and documentation

***

## Who Uses Toku Contractor?

### Clients (Administrators)

Organization admins use Toku Contractor to onboard contractors, manage engagements, and process payments.

<Card title="Client Guides" icon="user-gear" href="/contractor/client/onboarding-contractors">
  Learn how to manage contractors
</Card>

### Contractors

Contractors use Toku to submit invoices, track payments, and manage their profile.

<Card title="Contractor Guides" icon="user" href="/contractor/user/getting-started">
  Learn how to use the contractor portal
</Card>

***

## How It Works

```mermaid theme={null}
flowchart LR
    A[Onboard] --> B[Sign Contract]
    B --> C[Submit Invoice]
    C --> D[Approve]
    D --> E[Payment Sent]
    E --> F[Contractor Receives Funds]
```

***

## Key Features

<CardGroup>
  <Card title="Global Onboarding" icon="globe">
    Onboard contractors in 150+ countries with compliant contracts.
  </Card>

  <Card title="Invoicing" icon="file-invoice">
    Contractors submit invoices, admins review and approve.
  </Card>

  <Card title="Flexible Payments" icon="money-bill-wave">
    Pay in local currency, USD, crypto, or stablecoins.
  </Card>

  <Card title="Compliance" icon="shield-check">
    Built-in contractor classification and compliance checks.
  </Card>

  <Card title="Contract Management" icon="file-signature">
    Create, sign, and store contractor agreements.
  </Card>

  <Card title="Expense Tracking" icon="receipt">
    Track and reimburse contractor expenses.
  </Card>
</CardGroup>

***

## Example: Paying a Contractor in Singapore

Acme Corp hires Wei, a UX designer based in Singapore, for a 6-month engagement at \$8,000/month.

**1. Admin onboards Wei.** In Toku Contractor, the admin adds Wei's details, selects Singapore as the country, and generates a compliant contractor agreement. Wei signs electronically.

**2. Wei submits a monthly invoice.** At the end of the month, Wei logs into the contractor portal and submits an invoice for \$8,000 with a description of work completed.

**3. Admin reviews and approves.** The finance team reviews the invoice in the Payments dashboard and clicks "Approve." Wei has elected to receive payment via bank transfer in SGD.

```json theme={null}
{
  "invoiceID": "inv_3Rw7nQ",
  "contractor": "Wei Tan",
  "country": "Singapore",
  "amount": 8000.00,
  "currency": "USD",
  "paymentMethod": "Bank Transfer",
  "localCurrency": "SGD",
  "localAmount": 10720.00,
  "status": "Completed",
  "paidDate": "2025-02-03"
}
```

**4. Wei receives payment** in SGD directly to her bank account. Toku handles the currency conversion and ensures all tax documentation is properly filed for cross-border compliance.

***

## Payment Methods

| Method            | Description                                 |
| ----------------- | ------------------------------------------- |
| **Bank Transfer** | Direct deposit to contractor's bank account |
| **PayPal**        | Instant transfers via PayPal                |
| **Crypto**        | Payment in cryptocurrency                   |
| **Stablecoin**    | Payment in USDC, USDT, or other stablecoins |

***

## Getting Started

<CardGroup>
  <Card title="Onboard Contractors" icon="user-plus" href="/contractor/client/onboarding-contractors">
    Add your first contractor
  </Card>

  <Card title="Contractor Portal" icon="user" href="/contractor/user/getting-started">
    For contractors: get started
  </Card>
</CardGroup>

***

## Ready to use Toku?

<div>
  <div>
    <h3>Start onboarding global contractors</h3>

    <p>
      Manage compliant contractor relationships, invoices, and payments from one platform.
    </p>
  </div>

  <a href="https://www.toku.com/get-started">
    Sign up for Toku
  </a>
</div>


# Getting Started
Source: https://docs.toku.com/contractor/user/getting-started

Get started as a contractor on Toku

## Welcome to Toku

You've been invited to join Toku by a company that wants to work with you. This guide will help you complete onboarding and get paid.

***

## Completing Onboarding

<Steps>
  <Step title="Accept the invitation">
    Click the link in your invitation email to get started.
  </Step>

  <Step title="Create your account">
    Set up your Toku account with your email and a secure password.
  </Step>

  <Step title="Review the contract">
    Read the contractor agreement carefully before signing.
  </Step>

  <Step title="Sign electronically">
    Agree to the terms and sign the contract electronically.
  </Step>

  <Step title="Add payment information">
    Enter your payment details (bank account, PayPal, or crypto wallet).
  </Step>

  <Step title="Complete verification">
    Provide any required identity or tax documentation.
  </Step>
</Steps>

***

## Your Dashboard

After onboarding, your dashboard shows:

* **Active engagements** — Companies you're working with
* **Pending invoices** — Invoices awaiting approval
* **Payment history** — Past payments received
* **Documents** — Contracts and tax forms

***

## Key Actions

<CardGroup>
  <Card title="Submit Invoices" icon="file-invoice" href="/contractor/user/submitting-invoices">
    Bill for your work
  </Card>

  <Card title="Track Payments" icon="money-bill-wave" href="/contractor/user/receiving-payments">
    See payment status
  </Card>

  <Card title="Tax Info" icon="file" href="/contractor/user/tax-information">
    Manage tax documents
  </Card>

  <Card title="Profile" icon="user">
    Update your information
  </Card>
</CardGroup>

***

## Payment Methods

You can receive payments via:

* **Bank Transfer** — Direct deposit to your bank account
* **PayPal** — Instant transfers
* **Crypto** — Bitcoin, Ethereum, etc.
* **Stablecoin** — USDC, USDT

Set up your preferred payment method in **Settings** > **Payment Methods**.

***

## Getting Paid

The typical payment flow:

1. You submit an invoice for work completed
2. Your client reviews and approves
3. Payment is processed via your chosen method
4. You receive confirmation when payment is sent

<Card title="Submit Your First Invoice" icon="file-invoice" href="/contractor/user/submitting-invoices">
  Learn how to submit invoices
</Card>

***

## Need Help?

<CardGroup>
  <Card title="Contractor FAQ" icon="circle-question" href="/contractor/faq">
    Common questions
  </Card>

  <Card title="Contact Support" icon="headset" href="/getting-started/support">
    Get help from our team
  </Card>
</CardGroup>

***

<Tip>
  **Contractor Guide** — Step 1 of 4. [Next: Submitting Invoices](/contractor/user/submitting-invoices)
</Tip>


# Receiving Payments
Source: https://docs.toku.com/contractor/user/receiving-payments

Track and receive your contractor payments

## Overview

Once your invoice is approved, Toku processes your payment according to the schedule and method you've set up.

***

## Payment Flow

<Steps>
  <Step title="Invoice approved">
    Your client approves your submitted invoice
  </Step>

  <Step title="Payment scheduled">
    Payment is queued based on the payment schedule
  </Step>

  <Step title="Payment processed">
    Toku sends payment via your preferred method
  </Step>

  <Step title="Payment received">
    Funds arrive in your account
  </Step>
</Steps>

***

## Payment Methods

### Bank Transfer

* Direct deposit to your bank account
* Processing time: 2-5 business days
* Supports most countries and currencies

### PayPal

* Sent to your PayPal email
* Processing time: 1-2 business days
* Standard PayPal fees apply

### Cryptocurrency

* Sent to your crypto wallet address
* Processing time: Same day (network dependent)
* Supports Bitcoin, Ethereum, and others

### Stablecoin

* Sent to your wallet address
* Processing time: Same day
* Supports USDC, USDT on multiple networks

***

## Setting Up Payment Methods

<Steps>
  <Step title="Go to Settings">
    Click **Settings** in the sidebar
  </Step>

  <Step title="Select Payment Methods">
    Click **Payment Methods**
  </Step>

  <Step title="Add your method">
    Choose and configure your preferred method:

    * Bank: Enter account and routing numbers
    * PayPal: Enter your PayPal email
    * Crypto: Enter your wallet address
  </Step>

  <Step title="Set as default">
    Mark your primary payment method as default
  </Step>
</Steps>

***

## Processing Times

| Method               | Typical Time      |
| -------------------- | ----------------- |
| Bank (US)            | 2-3 business days |
| Bank (International) | 3-5 business days |
| PayPal               | 1-2 business days |
| Crypto               | Hours to 1 day    |
| Stablecoin           | Hours to 1 day    |

***

## Payment Schedule

Your client sets the payment schedule:

* **On Approval** — Paid immediately when invoice is approved
* **Weekly** — All approved invoices paid weekly
* **Bi-weekly** — Payments every two weeks
* **Monthly** — End-of-month payments

Check your engagement details to see your payment schedule.

***

## Tracking Payments

### Payment Status

| Status         | Meaning                                     |
| -------------- | ------------------------------------------- |
| **Pending**    | Invoice approved, payment not yet processed |
| **Processing** | Payment has been initiated                  |
| **Completed**  | Payment sent successfully                   |
| **Failed**     | Payment failed — check your payment method  |

### Payment History

View all past payments in **Payments** > **History**:

* Payment date and amount
* Payment method used
* Invoice reference
* Transaction details

***

## Payment Notifications

You'll receive notifications when:

* Your invoice is approved
* Payment is processing
* Payment has been completed
* There's an issue with payment

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Payment shows 'Failed'">
    Check that your payment details are correct. Update if needed and contact support to retry the payment.
  </Accordion>

  <Accordion title="Payment is taking longer than expected">
    Bank transfers can take up to 5 business days for international payments. If it's been longer, contact support.
  </Accordion>

  <Accordion title="I received less than expected">
    Check for any fees (PayPal fees, bank fees) or withholding that may have been deducted. View payment details for breakdown.
  </Accordion>
</AccordionGroup>

<Tip>
  **Contractor Guide** — Step 3 of 4. [Previous: Submitting Invoices](/contractor/user/submitting-invoices) | [Next: Tax Information](/contractor/user/tax-information)
</Tip>

***

## Next Steps

<Card title="Tax Information" icon="file" href="/contractor/user/tax-information">
  Manage your tax documents
</Card>


# Submitting Invoices
Source: https://docs.toku.com/contractor/user/submitting-invoices

How to create and submit invoices for your work

## Overview

Submit invoices through Toku to get paid for your work. Your client will review and approve your invoice before payment is processed.

***

## Creating an Invoice

<Steps>
  <Step title="Navigate to Invoices">
    Click **Invoices** in the sidebar
  </Step>

  <Step title="Click New Invoice">
    Select **Create Invoice** to start a new invoice
  </Step>

  <Step title="Select the client">
    Choose the engagement this invoice is for
  </Step>

  <Step title="Enter invoice details">
    Add the invoice information:

    * Invoice period (dates covered)
    * Description of work performed
    * Hours worked (if hourly)
    * Any additional line items
  </Step>

  <Step title="Attach documentation">
    Upload any supporting documents (optional):

    * Time logs
    * Deliverables
    * Receipts for reimbursables
  </Step>

  <Step title="Review and submit">
    Review the total and click **Submit Invoice**
  </Step>
</Steps>

***

## Invoice Details

| Field              | Description                        |
| ------------------ | ---------------------------------- |
| **Invoice Period** | The dates this invoice covers      |
| **Description**    | Summary of work performed          |
| **Hours**          | Total hours (if hourly engagement) |
| **Rate**           | Your agreed rate                   |
| **Subtotal**       | Hours × Rate or fixed amount       |
| **Expenses**       | Any reimbursable expenses          |
| **Total**          | Final invoice amount               |

***

## Hourly Engagements

For hourly work:

1. Enter total hours worked
2. Your rate is automatically applied
3. Add descriptions for each task or day
4. Attach time logs if required

### Time Tracking Tips

* Track hours daily for accuracy
* Note what you worked on
* Keep any time logs organized

***

## Fixed/Project-Based

For fixed-price work:

1. Reference the project or milestone
2. Enter the agreed amount
3. Describe what was delivered
4. Attach deliverables if required

***

## Adding Expenses

If your engagement includes expense reimbursement:

1. Click **Add Expense Line**
2. Enter expense description
3. Enter amount
4. Attach receipt
5. Expenses are added to your invoice total

***

## Invoice Status

| Status                | Meaning                          |
| --------------------- | -------------------------------- |
| **Draft**             | Started but not submitted        |
| **Submitted**         | Sent to client for review        |
| **Approved**          | Client approved, pending payment |
| **Paid**              | Payment completed                |
| **Changes Requested** | Client requested revisions       |
| **Rejected**          | Invoice declined                 |

***

## Revising an Invoice

If your client requests changes:

1. Go to the invoice
2. Read the client's feedback
3. Click **Edit Invoice**
4. Make the requested changes
5. Resubmit for approval

***

## Best Practices

* **Submit promptly** — Don't wait too long after work is completed
* **Be detailed** — Clear descriptions help approvals go faster
* **Include documentation** — Attach time logs or deliverables
* **Follow the schedule** — Submit on your agreed invoicing schedule

<Tip>
  **Contractor Guide** — Step 2 of 4. [Previous: Getting Started](/contractor/user/getting-started) | [Next: Receiving Payments](/contractor/user/receiving-payments)
</Tip>

***

## Next Steps

<Card title="Receiving Payments" icon="money-bill-wave" href="/contractor/user/receiving-payments">
  Learn about payment processing
</Card>


# Tax Information
Source: https://docs.toku.com/contractor/user/tax-information

Manage tax documents and information

## Overview

As a contractor, you're responsible for your own taxes. Toku helps by collecting required tax information and providing documentation for your records.

***

## Tax Documents

### Documents You Provide

Depending on your location, you may need to provide:

| Document             | Who                                  | Purpose                               |
| -------------------- | ------------------------------------ | ------------------------------------- |
| **W-9**              | US contractors                       | Tax identification for 1099 reporting |
| **W-8BEN**           | Non-US contractors (to US companies) | Foreign status certification          |
| **VAT Registration** | EU contractors                       | Value Added Tax number                |
| **Tax ID**           | Various countries                    | Local tax identification              |

### Documents You Receive

Toku provides:

* **Payment summaries** — Record of all payments received
* **1099** (US) — Annual tax form if you received \$600+ from a US client
* **Invoice history** — Complete record of your invoices

***

## Providing Tax Information

<Steps>
  <Step title="Navigate to Tax Info">
    Go to **Settings** > **Tax Information**
  </Step>

  <Step title="Select your country">
    Choose your country of tax residence
  </Step>

  <Step title="Complete required forms">
    Fill out the appropriate tax form (W-9, W-8BEN, etc.)
  </Step>

  <Step title="Enter tax ID">
    Provide your tax identification number
  </Step>

  <Step title="Sign electronically">
    Sign the form to certify the information
  </Step>
</Steps>

***

## For US Contractors

### W-9 Form

If you're a US person (citizen, resident, or entity), complete a W-9 with:

* Legal name
* Business name (if applicable)
* Tax classification
* Social Security Number or EIN
* Address

### 1099-NEC

If you receive \$600 or more from a US client in a calendar year, you'll receive a 1099-NEC form by January 31 of the following year.

***

## For Non-US Contractors

### W-8BEN / W-8BEN-E

If you're a non-US person working with a US company:

* Certifies your foreign status
* May reduce or eliminate US tax withholding
* Requires country of residence and foreign tax ID

### Withholding

Some payments to non-US contractors may be subject to US withholding (typically 30%, reduced by tax treaties).

***

## Tax Withholding

In some cases, taxes may be withheld from your payments:

* Check your payment details for any withholding
* Withheld amounts are remitted to tax authorities
* You receive documentation of amounts withheld

***

## Important Reminders

<Warning>
  This information is for reference only and does not constitute tax advice. Consult a qualified tax professional about your specific situation.
</Warning>

### Record Keeping

Keep records of:

* All invoices submitted
* All payments received
* Tax documents (W-9, 1099, etc.)
* Business expenses related to your contractor work

### Estimated Taxes

As a contractor, you may need to make estimated tax payments throughout the year. Check with a tax professional about your obligations.

***

## Accessing Tax Documents

<Steps>
  <Step title="Go to Documents">
    Click **Documents** in the sidebar
  </Step>

  <Step title="Select Tax Documents">
    Choose the **Tax Documents** tab
  </Step>

  <Step title="Select year">
    Choose the tax year
  </Step>

  <Step title="Download">
    Download your documents
  </Step>
</Steps>

***

## Need Help?

<Card title="Contractor FAQ" icon="circle-question" href="/contractor/faq">
  Common questions about contractor payments and taxes
</Card>

***

<Tip>
  **Contractor Guide** — Step 4 of 4. [Previous: Receiving Payments](/contractor/user/receiving-payments)
</Tip>


# Key Concepts
Source: https://docs.toku.com/getting-started/key-concepts

Terminology and concepts used throughout Toku

## Token Grant Administration

### Grant

A token grant is an award of tokens to an employee, contractor, or investor. Grants typically have vesting schedules that determine when the recipient can claim their tokens.

### Vesting

Vesting is the process by which a recipient earns the right to their tokens over time. Common vesting structures include:

* **Cliff vesting** — No tokens vest until a specific date (e.g., 1 year)
* **Linear vesting** — Tokens vest evenly over time (e.g., monthly over 4 years)
* **Milestone vesting** — Tokens vest when specific goals are achieved

### Distribution

A distribution is the actual transfer of vested tokens from your organization to a recipient's wallet.

### Cap Table

A record of all token grants and ownership in your organization, showing who owns what and how much has vested.

***

## Toku Contractor

### Contractor

An independent worker engaged by your organization on a contract basis, rather than as an employee.

### Invoice

A request for payment submitted by a contractor for work completed. Invoices include details like hours worked, rates, and total amount due.

### Engagement

The contractual relationship between your organization and a contractor, including terms, rates, and scope of work.

***

## Stablecoin Payroll

### Stablecoin

A cryptocurrency designed to maintain a stable value, typically pegged to a fiat currency like USD. Common stablecoins include USDC and USDT.

### Payroll Run

A scheduled payment to employees, including salary, bonuses, and any deductions.

### Withholding

The portion of an employee's pay that is held back for taxes or other deductions before payment is made.

### Payout Method

How an employee chooses to receive their pay — traditional bank transfer, stablecoin to a crypto wallet, or a combination.

***

## General Terms

### Custody Provider

A service that securely stores digital assets (tokens, stablecoins) on behalf of organizations. Toku integrates with providers like Fireblocks and Anchorage.

### Wallet

A digital account where tokens and stablecoins are stored. Recipients need a wallet address to receive crypto payments.

### KYC (Know Your Customer)

Identity verification required for compliance. Recipients may need to complete KYC before receiving payments.

***

## Related

<CardGroup>
  <Card title="TGA Overview" icon="coins" href="/tga/overview">
    Learn more about token grants
  </Card>

  <Card title="Contractor Overview" icon="user" href="/contractor/overview">
    Learn more about contractor management
  </Card>
</CardGroup>


# Onboarding Checklist
Source: https://docs.toku.com/getting-started/onboarding-checklist

Step-by-step guide for new Toku clients

## Getting Started with Toku

Follow this checklist to get your organization set up on Toku.

***

## Initial Setup

<Steps>
  <Step title="Access your account">
    You'll receive an invitation email from Toku. Click the link to set up your admin account and create your password.
  </Step>

  <Step title="Complete organization profile">
    Add your company information, including legal name, address, and tax details.
  </Step>

  <Step title="Add team members">
    Invite other admins who will help manage your Toku account.
  </Step>

  <Step title="Connect integrations">
    Set up your custody provider and any HR system integrations.
  </Step>
</Steps>

***

## Product-Specific Setup

### Token Grant Administration

<Steps>
  <Step title="Configure token details">
    Add your token information including contract address and network.
  </Step>

  <Step title="Set up vesting templates">
    Create standard vesting schedules for your grant programs.
  </Step>

  <Step title="Connect custody">
    Link your custody provider (Fireblocks, Anchorage, etc.) for token distributions.
  </Step>
</Steps>

<Card title="TGA Setup Guide" icon="arrow-right" href="/tga/client/setting-up-your-account">
  Complete TGA setup instructions
</Card>

### Toku Contractor

<Steps>
  <Step title="Configure payment methods">
    Set up how you'll pay contractors (bank transfer, crypto, etc.).
  </Step>

  <Step title="Add contractor templates">
    Create standard contract templates for different engagement types.
  </Step>

  <Step title="Set approval workflows">
    Define who approves contractor invoices and payments.
  </Step>
</Steps>

<Card title="Contractor Setup Guide" icon="arrow-right" href="/contractor/client/onboarding-contractors">
  Complete Contractor setup instructions
</Card>

### Stablecoin Payroll

<Steps>
  <Step title="Connect your HR system">
    Link your HRIS to sync employee data automatically.
  </Step>

  <Step title="Configure payroll settings">
    Set up pay schedules, currencies, and stablecoin options.
  </Step>

  <Step title="Enable employee opt-in">
    Allow employees to choose stablecoin payments.
  </Step>
</Steps>

<Card title="Payroll Setup Guide" icon="arrow-right" href="/payroll/client/enabling-stablecoin-payroll">
  Complete Payroll setup instructions
</Card>

***

## Need Help?

<Card title="Contact Support" icon="headset" href="/getting-started/support">
  Our team is here to help with setup
</Card>


# Overview
Source: https://docs.toku.com/getting-started/overview

What Toku does and how it helps your organization

## What is Toku?

Toku is the platform for managing token-based compensation and global contractor payments. We help organizations:

* **Issue and manage token grants** with customizable vesting schedules
* **Pay contractors globally** with instant payments in any currency
* **Run stablecoin payroll** with built-in compliance and tax withholding

***

## Our Products

<CardGroup>
  <Card title="Token Grant Administration" icon="coins" href="/tga/overview">
    Create grants, manage vesting, and distribute tokens to employees and investors.
  </Card>

  <Card title="Toku Contractor" icon="user" href="/contractor/overview">
    Onboard contractors, manage payments, and handle compliance across 150+ countries.
  </Card>

  <Card title="Stablecoin Payroll" icon="wallet" href="/payroll/overview">
    Pay employees in stablecoins with automatic tax withholding and reporting.
  </Card>
</CardGroup>

***

## Who Uses Toku?

### For Clients (Administrators)

Organization admins use Toku to set up and manage compensation programs, process payments, and ensure compliance.

### For Recipients (Employees, Contractors, Investors)

Recipients use Toku to view their grants, submit invoices, set up wallets, and receive payments.

***

## Next Steps

<CardGroup>
  <Card title="Onboarding Checklist" icon="list-check" href="/getting-started/onboarding-checklist">
    Step-by-step setup guide for new clients
  </Card>

  <Card title="Key Concepts" icon="book" href="/getting-started/key-concepts">
    Learn the terminology used throughout Toku
  </Card>
</CardGroup>


# Support
Source: https://docs.toku.com/getting-started/support

How to get help from the Toku team

## Contact Us

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:support@toku.com">
    [support@toku.com](mailto:support@toku.com)
  </Card>

  <Card title="Contact Form" icon="globe" href="https://www.toku.com/contact">
    [www.toku.com/contact](http://www.toku.com/contact)
  </Card>
</CardGroup>

***

## Self-Service Resources

<CardGroup>
  <Card title="TGA FAQ" icon="circle-question" href="/tga/faq">
    Token grant questions
  </Card>

  <Card title="Contractor FAQ" icon="circle-question" href="/contractor/faq">
    Contractor payment questions
  </Card>

  <Card title="Payroll FAQ" icon="circle-question" href="/payroll/faq">
    Stablecoin payroll questions
  </Card>

  <Card title="Key Concepts" icon="book" href="/getting-started/key-concepts">
    Terminology guide
  </Card>
</CardGroup>

***

## Enterprise Clients

Enterprise clients have a dedicated account manager for strategic guidance, custom configuration, and escalations. Check your welcome email for contact details.


# Toku
Source: https://docs.toku.com/index

Token grants, contractor management, and stablecoin payroll infrastructure.

<div>
  <h1>What is Toku?</h1>

  <p>
    Toku is the orchestration and payroll compliance layer for paying people in tokens and stablecoins. Whether you're issuing token grants, paying contractors globally, or running stablecoin payroll, Toku ensures tax withholding, reporting, and compliance are handled accurately and consistently across every workflow.
  </p>

  <div>
    <a href="/getting-started/overview">
      Get Started <Icon icon="arrow-right" />
    </a>
  </div>
</div>

<div>
  <div>
    <h2>Products</h2>
  </div>

  <CardGroup>
    <Card title="Token Grant Administration" icon="square-1" href="/tga/overview">
      Issue, vest, and distribute token grants to employees and investors — with built-in tax withholding and cap table tracking.
    </Card>

    <Card title="Stablecoin Payroll" icon="square-2" href="/payroll/overview">
      Pay employees in USDC or USDT alongside their regular salary, with automatic tax compliance and HRIS integration.
    </Card>

    <Card title="Contractor Payments" icon="square-3" href="/contractor/overview">
      Onboard and pay global contractors in 150+ countries with compliant contracts and flexible payment methods.
    </Card>
  </CardGroup>

  <div>
    <h2>Who Uses Toku?</h2>
  </div>

  <CardGroup>
    <Card title="Clients (Employers & Admins)" icon="building" href="/getting-started/onboarding-checklist">
      Set up token grant programs, enable stablecoin payroll, and onboard contractors — all from one dashboard.
    </Card>

    <Card title="Recipients (Employees & Contractors)" icon="user" href="/tga/user/employee-portal">
      View your grants, choose your payout method, set up your wallet, and track payments.
    </Card>
  </CardGroup>

  <div>
    <h2>Quickstarts</h2>
  </div>

  <CardGroup>
    <Card title="Set up Token Grants" icon="rocket" href="/tga/client/setting-up-your-account">
      Configure your first token grant program in minutes.
    </Card>

    <Card title="Onboard Contractors" icon="user-plus" href="/contractor/client/onboarding-contractors">
      Start paying global contractors with compliant contracts.
    </Card>

    <Card title="Enable Stablecoin Payroll" icon="money-bill-wave" href="/payroll/client/enabling-stablecoin-payroll">
      Let employees receive salary in USDC or other stablecoins.
    </Card>
  </CardGroup>

  <div>
    <h2>Integration</h2>
  </div>

  <CardGroup>
    <Card title="Integration Guide" icon="plug" href="/integration-guide/overview">
      Embed Toku payroll, EOR, and stablecoin payments into your platform
    </Card>
  </CardGroup>

  <div>
    <div>
      <div>
        <h3>Discover why leading companies choose Toku</h3>

        <p>
          No matter your use case, connect with our team and we'll help match you with the right Toku solution.
        </p>
      </div>

      <a href="https://www.toku.com/get-started">
        Sign up for Toku
      </a>
    </div>
  </div>
</div>


# Create HRIS Person
Source: https://docs.toku.com/integration-guide/endpoints/eor/create-hris-person

POST /createHrisPerson
Creates an employee or contractor record using the requested employment type payload.



# Get HRIS People
Source: https://docs.toku.com/integration-guide/endpoints/eor/get-hris-people

GET /getHrisPeople
Returns employee and contractor people records for the authenticated organization.



# Get HRIS Person
Source: https://docs.toku.com/integration-guide/endpoints/eor/get-hris-person

POST /getHrisPerson
Returns a single HRIS person by role-in-org identifier.



# Get Onboarding Overview
Source: https://docs.toku.com/integration-guide/endpoints/eor/get-onboarding-overview

GET /getOnboardingOverview
Returns onboarding progress overview rows for workers in the authenticated organization.



# Get Onboarding Progress
Source: https://docs.toku.com/integration-guide/endpoints/eor/get-onboarding-progress

POST /getOnboardingProgress
Returns detailed onboarding progress, including individual onboarding steps.



# Update HRIS Employee Profile
Source: https://docs.toku.com/integration-guide/endpoints/eor/update-hris-employee-profile

PUT /updateHrisEmployeeProfile
Submits profile updates for an HRIS employee.



# Update HRIS Person
Source: https://docs.toku.com/integration-guide/endpoints/eor/update-hris-person

POST /updateHrisPerson
Updates editable HRIS person profile fields.



# Create Payroll
Source: https://docs.toku.com/integration-guide/endpoints/payroll/create-payroll

POST /createPayroll
Creates a payroll run with the requested pay period, currency, token type, and payroll entity.



# Get All Payrolls
Source: https://docs.toku.com/integration-guide/endpoints/payroll/get-all-payroll

GET /getAllPayroll
Returns all payroll runs for the authenticated organization.



# Get Payroll
Source: https://docs.toku.com/integration-guide/endpoints/payroll/get-payroll

POST /getPayroll
Returns a single payroll run by identifier.



# Update Payroll State
Source: https://docs.toku.com/integration-guide/endpoints/payroll/update-payroll-state

POST /updatePayrollState
Transitions a payroll run to a new lifecycle state.



# Validate and Calculate Payroll
Source: https://docs.toku.com/integration-guide/endpoints/payroll/validate-calculate-payroll

POST /validateAndCalculatePayroll
Validates employee payroll rows and returns calculated payroll breakdown data.



# Create Payslip
Source: https://docs.toku.com/integration-guide/endpoints/payslips/create-hris-payslip

POST /createHrisPayslip
Creates a payslip record referencing an uploaded payslip file.



# Create Payslip File Upload
Source: https://docs.toku.com/integration-guide/endpoints/payslips/create-hris-payslip-file-upload

POST /createHrisPayslipFileUpload
Generates a pre-signed URL for uploading a payslip PDF.



# Get Payslip Download URL
Source: https://docs.toku.com/integration-guide/endpoints/payslips/get-hris-payslip-download-url

POST /getHrisPayslipDownloadUrl
Returns a pre-signed download URL for an uploaded payslip file.



# Get Payslips for Employee
Source: https://docs.toku.com/integration-guide/endpoints/payslips/get-hris-payslips-for-employee

POST /getHrisPayslipsForEmployee
Returns payslips for a single employee.



# Get Payslips for Org
Source: https://docs.toku.com/integration-guide/endpoints/payslips/get-hris-payslips-for-org

POST /getHrisPayslipsForOrg
Returns payslips for the organization with dashboard summary information.



# Approve Token Payroll Settlements
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/approve-token-payroll-settlements

POST /approveTokenPayrollSettlements
Approves wallet references and pending settlements for a token payroll.



# Compute Pending Settlements
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/compute-pending-settlements

POST /computePendingSettlements
Computes pending settlement records for a token payroll.



# Create Token Payroll
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/create-token-payroll

POST /createTokenPayroll
Creates a token payroll run for stablecoin settlement.



# Get All Token Payrolls
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/get-all-token-payrolls

GET /getAllTokenPayrolls
Returns token payroll runs, optionally filtered by payroll entity.



# Get Token Payroll Breakdown
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/get-token-payroll-breakdown

POST /getTokenPayrollBreakdown
Returns token distribution breakdown data for a worker net pay amount.



# Get Token Payroll By ID
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/get-token-payroll-by-id

POST /getTokenPayrollByID
Returns a token payroll by identifier.



# Update Token Payroll State
Source: https://docs.toku.com/integration-guide/endpoints/stablecoin/update-token-payroll-state

POST /updateTokenPayrollState
Transitions a token payroll to a new lifecycle state.



# Create Webhook Endpoint
Source: https://docs.toku.com/integration-guide/endpoints/webhooks/create-webhook-endpoint

POST /createWebhookEndpoint
Creates a webhook endpoint and returns its signing secret.



# Delete Webhook Endpoint
Source: https://docs.toku.com/integration-guide/endpoints/webhooks/delete-webhook-endpoint

DELETE /deleteWebhookEndpoint
Deletes a webhook endpoint by identifier.



# List Webhook Deliveries
Source: https://docs.toku.com/integration-guide/endpoints/webhooks/list-webhook-deliveries

GET /listWebhookDeliveries
Returns delivery attempts for a specific webhook endpoint.



# List Webhook Endpoints
Source: https://docs.toku.com/integration-guide/endpoints/webhooks/list-webhook-endpoints

GET /listWebhookEndpoints
Returns webhook endpoints configured for the authenticated organization.



# Authentication
Source: https://docs.toku.com/integration-guide/guides/authentication

Partner authentication flow and API token lifecycle

## Overview

Partner authentication in Toku uses scoped API tokens. Your backend obtains a token by calling the `createUserApiToken` endpoint with your organization credentials, then includes that token in all subsequent API requests.

<Note>
  Before you begin, you'll need organization credentials from Toku. Contact Toku to provision your organization and obtain initial credentials.
</Note>

## Token Exchange Flow

For detailed information on token concepts and security best practices, see [API Authentication](/api/authentication).

<Steps>
  <Step title="Obtain initial credentials">
    Toku provisions your organization with initial credentials during onboarding. Store these securely.
  </Step>

  <Step title="Create an API token">
    Call `POST /createUserApiToken` with your organization credentials:

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createUserApiToken \
      -H "Authorization: Bearer INITIAL_CREDENTIAL" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "your-email@company.com",
        "orgID": "org-uuid",
        "roleInOrgID": "CLIENT_ORG_ADMIN"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "personalToken": {
        "token": "toku_live_...",
        "personalTokenID": "token-uuid",
        "expiresAt": "2026-05-07T03:05:00Z"
      }
    }
    ```

    **Store the token securely** — it cannot be retrieved again.
  </Step>

  <Step title="Use the token in requests">
    Include the token in every API request:

    ```bash theme={null}
    curl https://app.toku.com/api/tokuApi/v1/listGrants \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: CLIENT_ORG_ADMIN"
    ```
  </Step>

  <Step title="Refresh before expiry">
    Tokens expire after 30 days. Refresh before expiry using `POST /refreshUserApiToken`:

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/refreshUserApiToken \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json"
    ```

    Response:

    ```json theme={null}
    {
      "personalToken": {
        "token": "toku_live_...",
        "personalTokenID": "token-uuid",
        "expiresAt": "2026-06-06T03:05:00Z"
      }
    }
    ```
  </Step>
</Steps>

## Required Headers

Every request must include these headers:

| Header          | Required            | Description                              |
| --------------- | ------------------- | ---------------------------------------- |
| `Authorization` | Yes                 | `Bearer YOUR_API_TOKEN`                  |
| `x-role-type`   | Yes                 | Role context for the request (see below) |
| `Content-Type`  | For POST/PUT/DELETE | Must be `application/json`               |

## Token Scoping

Each API token is scoped to a single organization and inherits the permissions of the user who created it. If the user's role is revoked, the token stops working.

### Role Types

The `x-role-type` header determines request permissions:

| Role               | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `CLIENT_ORG_ADMIN` | Full administrative access to the organization       |
| `PAYROLL_ADMIN`    | Access to payroll and settlement operations          |
| `FINANCE_ADMIN`    | Access to financial reporting and payment operations |
| `INVESTOR`         | Read access to investment and warrant data           |

## Rate Limits

API requests are rate-limited to **100 requests per minute per IP**. For details on rate limit errors and other error responses, see [Error Handling](/api/errors).

## Next Steps

<CardGroup>
  <Card title="Create API Token" icon="key" href="/integration-guide/endpoints/auth/create-api-token">
    Endpoint reference for token creation
  </Card>

  <Card title="Refresh API Token" icon="rotate" href="/integration-guide/endpoints/auth/refresh-api-token">
    Endpoint reference for token refresh
  </Card>
</CardGroup>


# Employer of Record
Source: https://docs.toku.com/integration-guide/guides/eor

Manage EOR employees through Toku — onboarding, profile updates, and status tracking

## Overview

Employer of Record (EOR) lets your platform offer employment services in jurisdictions where you lack a legal entity. Toku acts as the legal employer: handling compliance, payroll, and local labor law obligations while you manage the employment relationship through the API.

<Note>
  EOR operations require your API token to be scoped to a user with the `PAYROLL_ADMIN` or `CLIENT_ORG_ADMIN` role. Pass the appropriate role in the `x-role-type` header on every request.
</Note>

## Role Mapping

| Role            | `x-role-type` value | Permitted operations                                  |
| --------------- | ------------------- | ----------------------------------------------------- |
| Admin           | `CLIENT_ORG_ADMIN`  | All EOR operations including create, update, and view |
| Payroll manager | `PAYROLL_ADMIN`     | View people, onboarding progress, and profile updates |
| Employee        | *(managed by Toku)* | Completes onboarding steps via the co-branded UI      |

## Employee Onboarding Flow

When you add a new EOR employee, Toku creates a structured onboarding checklist. The employee completes the required steps (personal details, bank account, tax forms, etc.) through your platform's co-branded onboarding UI. Once all steps are done, Toku activates the employment relationship.

<Steps>
  <Step title="Create person record">
    Call `POST /createHrisPerson` with `employmentType: EMPLOYEE` and `employmentServiceType: EOR`. Supply the employee's name, email, country, start date, title, and compensation.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createHrisPerson \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "employmentType": "EMPLOYEE",
        "employmentServiceType": "EOR",
        "givenName": "Ada",
        "familyName": "Lovelace",
        "email": "ada@example.com",
        "country": "SG",
        "startDate": "2026-05-01",
        "title": "Software Engineer",
        "baseSalary": 120000,
        "baseSalaryCurrency": "SGD"
      }'
    ```

    The response includes `roleInOrgID` — store this to reference the employee in all subsequent calls.

    ```json theme={null}
    {
      "roleInOrgID": "role-uuid",
      "email": "ada@example.com",
      "fullName": "Ada Lovelace"
    }
    ```
  </Step>

  <Step title="Monitor onboarding progress">
    Poll `POST /getOnboardingProgress` with the employee's `roleInOrgId` to track each step. The response lists every required step with its completion status.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/getOnboardingProgress \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{ "roleInOrgId": "role-uuid" }'
    ```
  </Step>

  <Step title="Employee completes onboarding steps">
    Direct the employee to your platform's co-branded onboarding UI. Toku renders white-labelled onboarding forms within your product so employees stay in your experience. Steps typically include personal information, address, bank account, and tax declarations.
  </Step>

  <Step title="Employee activated">
    When all required steps are complete, the employee's status transitions to `ACTIVE`. Query `POST /getHrisPerson` to confirm the current status before processing payroll.
  </Step>
</Steps>

## Listing and Looking Up People

### Get all people

`GET /getHrisPeople` returns your organisation's full people directory — EOR employees, contractors, and any other person records. Use this for building org charts, dashboards, or payroll runs.

Each record includes `id`, `fullName`, `email`, `type`, `status`, `title`, and `department`.

### Get a single person

`POST /getHrisPerson` takes a `roleInOrgID` and returns the full person object including employment details and current status.

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/getHrisPerson \
  -H "Authorization: Bearer toku_live_..." \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{ "roleInOrgID": "role-uuid" }'
```

## Profile Management

### Basic field updates

`POST /updateHrisPerson` applies lightweight updates such as name corrections, title changes, manager reassignments, or phone number updates. Changes take effect immediately and do not create a change request.

Updatable fields: `givenName`, `familyName`, `title`, `department`, `phoneNumber`, `managerEmail`.

### Profile-level updates

`PUT /updateHrisEmployeeProfile` handles changes that may affect employment terms (e.g., compensation, role changes). These updates trigger a **change request** workflow inside Toku for compliance review. The response includes a `changeRequestId` that you can use to track approval status.

```json theme={null}
{
  "success": true,
  "updatedFields": ["title", "department"],
  "changeRequestId": "cr-uuid"
}
```

## Onboarding Overview

`GET /getOnboardingOverview` returns aggregate onboarding status across all employees — useful for building an admin dashboard that surfaces who is pending, in-progress, or fully onboarded.

## Co-Branded Experience

Toku's onboarding UI renders within your platform via an embedded flow. Employees see your branding throughout the onboarding process. No redirect to a Toku-hosted domain is required.

<Note>
  Contact Toku to configure your brand assets (logo, colors, domain) for the co-branded onboarding experience.
</Note>

## Next Steps

<CardGroup>
  <Card title="Create HRIS Person" icon="user-plus" href="/integration-guide/endpoints/eor/create-hris-person">
    Create an EOR employee or contractor record
  </Card>

  <Card title="Get Onboarding Progress" icon="list-check" href="/integration-guide/endpoints/eor/get-onboarding-progress">
    Track step-by-step onboarding completion
  </Card>

  <Card title="Get HRIS People" icon="users" href="/integration-guide/endpoints/eor/get-hris-people">
    List all people in your organisation
  </Card>

  <Card title="Update HRIS Employee Profile" icon="pen" href="/integration-guide/endpoints/eor/update-hris-employee-profile">
    Submit profile changes for compliance review
  </Card>
</CardGroup>


# Payroll
Source: https://docs.toku.com/integration-guide/guides/payroll

Payroll run lifecycle from creation to disbursement

## Overview

A payroll run moves through a defined set of states before funds reach employees. Each state transition is explicit — your integration drives the run from draft creation through validation, approval, and funding.

## Payroll State Machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> DRAFT: createPayroll
    DRAFT --> CALCULATING: validateAndCalculatePayroll
    CALCULATING --> APPROVED: updatePayrollState(APPROVED)
    APPROVED --> FUNDING: updatePayrollState(FUNDING)
    FUNDING --> COMPLETED: updatePayrollState(COMPLETED)
    DRAFT --> FAILED
    CALCULATING --> FAILED
    APPROVED --> FAILED
    FUNDING --> FAILED
```

| State         | Meaning                                                |
| ------------- | ------------------------------------------------------ |
| `DRAFT`       | Run created; employee data not yet validated           |
| `CALCULATING` | `validateAndCalculatePayroll` called; net pay computed |
| `APPROVED`    | Payroll approved; ready to fund                        |
| `FUNDING`     | Funding transfer in progress                           |
| `COMPLETED`   | Employees paid; run closed                             |
| `FAILED`      | Terminal error; create a new run to retry              |

***

## Payroll Run Lifecycle

<Steps>
  <Step title="Create the payroll run">
    Call `POST /createPayroll` to open a new run in `DRAFT` state. Specify the pay period, currency, and entity.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createPayroll \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: PAYROLL_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "payrollName": "April 2026 — Global Engineering",
        "payrollStartDate": "2026-04-01T00:00:00.000Z",
        "payrollEndDate": "2026-04-30T23:59:59.000Z",
        "payrollPayDate": "2026-05-02T00:00:00.000Z",
        "payrollFiatCurrency": "USD",
        "tokenTypeID": "usdc-mainnet",
        "payrollEntity": "entity-uuid"
      }'
    ```

    The response includes a `payrollId` you'll use in every subsequent call.
  </Step>

  <Step title="Validate and calculate net pay">
    Submit employee compensation data to `POST /validateAndCalculatePayroll`. This step validates employee records and computes gross-to-net figures for each employee before any funds move.

    ```json theme={null}
    {
      "payrollId": "payroll-uuid",
      "employeeData": [
        {
          "employeeId": "emp-uuid-001",
          "grossSalary": 8000,
          "currency": "USD"
        },
        {
          "employeeId": "emp-uuid-002",
          "grossSalary": 6500,
          "currency": "USD"
        }
      ]
    }
    ```

    A successful response transitions the run to `CALCULATING` and returns per-employee net pay figures. Fix any validation errors before proceeding.
  </Step>

  <Step title="Approve the payroll run">
    Call `POST /updatePayrollState` with `state: "APPROVED"` to confirm the calculated figures.

    ```json theme={null}
    {
      "payrollId": "payroll-uuid",
      "state": "APPROVED"
    }
    ```
  </Step>

  <Step title="Initiate funding">
    Move the run to `FUNDING` state to trigger the disbursement transfer. For stablecoin-funded payrolls, see [Stablecoin Funding](/integration-guide/guides/stablecoin-funding) for wallet pre-funding requirements.

    ```json theme={null}
    {
      "payrollId": "payroll-uuid",
      "state": "FUNDING"
    }
    ```
  </Step>

  <Step title="Mark as completed">
    Once the platform confirms funds have been disbursed, update the state to `COMPLETED`.

    ```json theme={null}
    {
      "payrollId": "payroll-uuid",
      "state": "COMPLETED"
    }
    ```
  </Step>
</Steps>

***

## Off-Cycle Runs

Not all payrolls follow the standard monthly schedule. Use the `type` field on `createPayroll` to differentiate run types:

| Type          | Use case                                          |
| ------------- | ------------------------------------------------- |
| `REGULAR`     | Standard scheduled payroll                        |
| `BONUS`       | One-time bonus payments outside the regular cycle |
| `CORRECTION`  | Retroactive corrections to a prior run            |
| `TERMINATION` | Final pay for departing employees                 |

Off-cycle runs follow the same lifecycle — create, validate, approve, fund, complete — but can be initiated at any time.

***

## Multi-Currency Payrolls

Contracts are denominated in a local fiat currency specified by `payrollFiatCurrency` (e.g., `"USD"`, `"SGD"`, `"EUR"`). The platform handles FX conversion internally.

For payrolls funded via stablecoin, set `tokenTypeID` to the desired token (e.g., `"usdc-mainnet"`). The funding step debits the pre-loaded stablecoin wallet and converts to local currency for each employee.

<Note>
  `payrollFiatCurrency` and `tokenTypeID` must be set at run creation and cannot be changed after the run leaves `DRAFT`.
</Note>

***

## Employee Validation

`validateAndCalculatePayroll` performs these checks before net pay is computed:

* Employee records are active and linked to the payroll entity
* Required compensation fields are present and within allowed ranges
* Currency codes match the contract currency for each employee

Validation errors are returned per-employee in the response. Correct the data and resubmit — the run stays in `DRAFT` until validation passes.

***

## Retrieving Payroll Runs

* **List all runs** — `GET /getAllPayroll` returns every payroll run for your organization, including state and metadata.
* **Fetch a single run** — `POST /getPayroll` with a `payrollId` returns the full run object including per-employee results after validation.

***

## Next Steps

<CardGroup>
  <Card title="Create Payroll" icon="plus" href="/integration-guide/endpoints/payroll/create-payroll">
    Endpoint reference for opening a new run
  </Card>

  <Card title="Validate & Calculate" icon="calculator" href="/integration-guide/endpoints/payroll/validate-calculate-payroll">
    Endpoint reference for employee validation and net pay
  </Card>

  <Card title="Update Payroll State" icon="arrow-right" href="/integration-guide/endpoints/payroll/update-payroll-state">
    Endpoint reference for state transitions
  </Card>

  <Card title="Stablecoin Funding" icon="coins" href="/integration-guide/guides/stablecoin-funding">
    Pre-fund your wallet before initiating payroll
  </Card>
</CardGroup>


# Payslips
Source: https://docs.toku.com/integration-guide/guides/payslips

Payslip generation, file upload, and retrieval

## Overview

Toku supports two payslip workflows: **automatic generation** after a payroll run completes, and **manual upload** of PDF payslips. Both produce `hrisPayslip` records that employees can download via presigned URLs.

## Payslip Generation

When a payroll run finishes, Toku automatically generates payslips and fires a `payslip.generated` webhook event. Subscribe to this event to know when payslips are ready. For webhook setup, see [Webhooks](/integration-guide/guides/webhooks).

```json theme={null}
{
  "event": "payslip.generated",
  "data": {
    "hrisPayslipID": "payslip-uuid",
    "roleInOrgID": "role-uuid",
    "payslipDate": "2025-03"
  }
}
```

## File Upload Flow

To upload an external PDF payslip, follow this three-step process. The PDF must be under **20 MB** (`fileSizeInBytes` ≤ 20971520).

<Steps>
  <Step title="Request a presigned upload URL">
    Call `POST /createHrisPayslipFileUpload` with the file metadata. The response contains a `fileID` and a presigned `uploadUrl` for S3.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createHrisPayslipFileUpload \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "roleInOrgID": "role-uuid",
        "fileName": "payslip-march-2025.pdf",
        "fileMimeType": "application/pdf",
        "fileSizeInBytes": 102400
      }'
    ```

    Response:

    ```json theme={null}
    {
      "fileID": "file-uuid",
      "fileName": "payslip-march-2025.pdf",
      "fileMimeType": "application/pdf",
      "fileSizeInBytes": 102400,
      "uploadUrl": "https://storage.example.com/...?X-Amz-Signature=..."
    }
    ```

    Save both `fileID` and `uploadUrl` — you need them in the next steps.
  </Step>

  <Step title="Upload the PDF directly to S3">
    `PUT` the raw PDF binary to the presigned `uploadUrl`. **No Toku authorization header is needed** — the presigned URL includes all required credentials.

    ```bash theme={null}
    curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
      -H "Content-Type: application/pdf" \
      --data-binary @payslip-march-2025.pdf
    ```

    A `200 OK` response confirms the upload succeeded. If S3 returns an error, the presigned URL may have expired — request a new one from Step 1.
  </Step>

  <Step title="Register the payslip with Toku">
    Call `POST /createHrisPayslip` with the `fileID` from Step 1 and the payslip financial details.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createHrisPayslip \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "roleInOrgID": "role-uuid",
        "fileID": "file-uuid",
        "currencyID": "SGD",
        "payslipDate": "2025-03",
        "grossAmount": 5000.00,
        "netAmount": 4200.00
      }'
    ```

    Response:

    ```json theme={null}
    {
      "hrisPayslipID": "payslip-uuid"
    }
    ```

    The returned `hrisPayslipID` is the stable identifier for this payslip record.
  </Step>
</Steps>

## Retrieving Payslips

### Organization-level listing

Use `POST /getHrisPayslipsForOrg` to list all payslips across an organization with optional filters:

| Parameter    | Type     | Description                          |
| ------------ | -------- | ------------------------------------ |
| `search`     | string?  | Search by employee name or file name |
| `periodKey`  | string?  | Filter by period in `YYYY-MM` format |
| `department` | string?  | Filter by department                 |
| `limit`      | integer? | Results per page (1–200, default 10) |
| `offset`     | integer? | Pagination offset                    |

The response includes `totalCount`, a `payslips[]` array, and a `dashboardSummary`.

### Employee-level listing

Use `POST /getHrisPayslipsForEmployee` with a `roleInOrgID` to retrieve all payslips for a specific employee.

## Downloading Payslips

Call `POST /getHrisPayslipDownloadUrl` with an `hrisPayslipID` to get a short-lived presigned download URL:

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/getHrisPayslipDownloadUrl \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{ "hrisPayslipID": "payslip-uuid" }'
```

Response:

```json theme={null}
{
  "hrisPayslipID": "payslip-uuid",
  "fileID": "file-uuid",
  "fileName": "payslip-march-2025.pdf",
  "mimeType": "application/pdf",
  "downloadUrl": "https://storage.example.com/...?X-Amz-Signature=..."
}
```

Redirect the employee's browser to `downloadUrl` or proxy it from your backend. The URL is short-lived — do not cache it.

## Endpoints

<CardGroup>
  <Card title="Create Payslip File Upload" icon="upload" href="/integration-guide/endpoints/payslips/create-hris-payslip-file-upload">
    Get a presigned S3 URL for PDF upload
  </Card>

  <Card title="Create Payslip" icon="file-lines" href="/integration-guide/endpoints/payslips/create-hris-payslip">
    Register an uploaded file as a payslip record
  </Card>

  <Card title="Get Payslips for Org" icon="building" href="/integration-guide/endpoints/payslips/get-hris-payslips-for-org">
    List all payslips with search and filters
  </Card>

  <Card title="Get Payslips for Employee" icon="user" href="/integration-guide/endpoints/payslips/get-hris-payslips-for-employee">
    List payslips for a specific employee
  </Card>

  <Card title="Get Payslip Download URL" icon="download" href="/integration-guide/endpoints/payslips/get-hris-payslip-download-url">
    Get a presigned URL to download a payslip PDF
  </Card>
</CardGroup>


# Stablecoin Funding
Source: https://docs.toku.com/integration-guide/guides/stablecoin-funding

Fund Toku payroll runs using stablecoins — Toku handles fiat disbursement to employees

## Overview

Stablecoin Funding lets partners pre-fund payroll runs by transferring stablecoins (USDC, USDT, and others) on-chain to Toku's custody. Toku then converts and disburses local-currency payments to employees. Your integration never handles fiat directly — you transfer tokens, Toku handles the rest.

**Key characteristics:**

* Contracts are denominated in local fiat (e.g., SGD, USD, EUR)
* You fund in stablecoins; the exchange rate is locked at settlement time
* Each payroll entity may have one or more custodial wallets; transfers are per-wallet
* `computePendingSettlements` always shows the exact token amount required before you commit funds

***

## End-to-End Funding Flow

<Steps>
  <Step title="Create a token payroll run">
    Call `POST /createTokenPayroll` to open a new run in draft state. Specify the pay period, tax currency, and the payroll entity.

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/createTokenPayroll \
      -H "Authorization: Bearer toku_live_..." \
      -H "x-role-type: PAYROLL_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "payPeriodStart": "2026-04-01T00:00:00.000Z",
        "payPeriodEnd": "2026-04-30T23:59:59.000Z",
        "payDate": "2026-05-02T00:00:00.000Z",
        "fiatCurrency": "SGD",
        "payrollEntityId": "entity-uuid-abc",
        "externalPayrollID": "apr-2026-sg-crypto"
      }'
    ```

    The response includes a `tokenPayrollID` used in every subsequent call.
  </Step>

  <Step title="Compute pending settlements">
    Call `POST /computePendingSettlements` with the `payrollID`. The response lists each custodial wallet that requires funding, along with the exact token amount, equivalent fiat amount, and the exchange rate that will be applied.

    ```json theme={null}
    {
      "payrollID": "token-payroll-uuid"
    }
    ```

    Review the `pendingSettlements` array carefully. Each entry shows:

    * `walletAddress` — on-chain destination for your transfer
    * `tokenAmount` — exact amount to send (in token units)
    * `fiatAmount` — fiat equivalent at current rate
    * `exchangeRate` — rate locked at settlement approval

    <Note>
      Do not send funds until you have reviewed pending settlements. The rate shown here is the rate that will be applied when you call `approveTokenPayrollSettlements`.
    </Note>
  </Step>

  <Step title="Transfer stablecoins on-chain">
    Using the wallet addresses and token amounts from Step 2, transfer stablecoins from your wallet(s) to Toku's custody addresses. Use your own signing infrastructure for this on-chain step.

    Ensure transfers are confirmed on-chain before proceeding to the next step.
  </Step>

  <Step title="Approve the settlements">
    Call `POST /approveTokenPayrollSettlements` with the `tokenPayrollID` and the `walletReferenceIDs` for each wallet you funded. Toku verifies on-chain receipt and locks in the exchange rates.

    ```json theme={null}
    {
      "tokenPayrollID": "token-payroll-uuid",
      "walletReferenceIDs": ["wallet-ref-001", "wallet-ref-002"]
    }
    ```

    A successful response returns `"success": true` and the count of approved settlements.
  </Step>

  <Step title="Toku disburses to employees">
    After approval, Toku converts the received tokens to local fiat and processes disbursements to each employee. The run transitions to `COMPLETED` when all payments have been sent.

    Monitor state via `POST /getTokenPayrollByID` or webhook events for the `token_payroll.completed` event.
  </Step>
</Steps>

***

## Listing and Lookup

### List all token payrolls

`GET /getAllTokenPayrolls` returns every token payroll run for your organization. You can filter by entity:

```
GET /getAllTokenPayrolls?payrollEntityId=entity-uuid-abc
```

The response is an array of token payroll objects with their current state, pay period, and entity.

### Fetch a single run

`POST /getTokenPayrollByID` returns the full payroll object including contributor details, settlement method, and current state.

```json theme={null}
{
  "tokenPayrollID": "token-payroll-uuid"
}
```

Pass an optional `payrollTypes` array to filter by run type (e.g., `["REGULAR", "BONUS"]`).

***

## State Management

Use `POST /updateTokenPayrollState` to advance or halt a run's lifecycle.

```json theme={null}
{
  "tokenPayrollId": "token-payroll-uuid",
  "state": "APPROVED"
}
```

| State       | Meaning                                      |
| ----------- | -------------------------------------------- |
| `DRAFT`     | Run created; awaiting settlement computation |
| `APPROVED`  | Settlements approved; disbursement queued    |
| `FUNDING`   | On-chain transfer in progress                |
| `COMPLETED` | All employees paid; run closed               |
| `FAILED`    | Terminal error; create a new run to retry    |

<Warning>
  State transitions are validated server-side. Attempting an invalid transition (e.g., `COMPLETED` → `DRAFT`) returns a `400` error.
</Warning>

***

## Per-Employee Breakdown

`POST /getTokenPayrollBreakdown` returns the token distribution for a specific role in the organization. Pass `roleInOrgID` and the calculated `netPay` to see how the net pay maps to token amounts per employee.

The response includes:

* `tokenDistributions` — list of token allocation rules applied
* `tokenAmounts` — per-token amounts after applying distributions
* `totalTokenPercentage` — percentage of net pay covered by tokens
* `netFiatPay` — remainder paid in fiat after token allocation

This is useful for reconciliation and for presenting pre-funding breakdowns to finance teams.

***

## Multi-Currency Notes

Contracts are always denominated in a local fiat currency set via `fiatCurrency` at run creation. Employees receive payment in their contract currency regardless of which stablecoin you use to fund.

Exchange rates are **locked at settlement approval time** — the rate shown in `computePendingSettlements` is indicative until `approveTokenPayrollSettlements` is called, at which point it is fixed for that run. Rate slippage between computation and approval is your responsibility to manage.

***

## Next Steps

<CardGroup>
  <Card title="Create Token Payroll" icon="plus" href="/integration-guide/endpoints/stablecoin/create-token-payroll">
    Open a new stablecoin payroll run
  </Card>

  <Card title="Compute Pending Settlements" icon="calculator" href="/integration-guide/endpoints/stablecoin/compute-pending-settlements">
    Get required token amounts before funding
  </Card>

  <Card title="Approve Settlements" icon="circle-check" href="/integration-guide/endpoints/stablecoin/approve-token-payroll-settlements">
    Confirm on-chain transfers and lock rates
  </Card>

  <Card title="Get Payroll Breakdown" icon="chart-bar" href="/integration-guide/endpoints/stablecoin/get-token-payroll-breakdown">
    Per-employee token distribution details
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.toku.com/integration-guide/guides/webhooks

Receive real-time event notifications from Toku via HTTPS POST to your registered endpoint

## Overview

Toku sends an HTTPS `POST` request to your registered endpoint whenever a subscribed event occurs. Your endpoint must respond with a `2xx` status within **10 seconds** to be considered a successful delivery.

Webhooks are scoped to your integration. Each endpoint you register receives only the event types you explicitly subscribe to.

***

## Endpoint Management

Register an endpoint with [`POST /createWebhookEndpoint`](/integration-guide/endpoints/webhooks/create-webhook-endpoint). Supply a valid `https://` URL and the array of event types you want to receive.

```json theme={null}
{
  "url": "https://your-service.example.com/webhooks/toku",
  "events": ["payroll_run.created", "payroll_run.completed"]
}
```

The response includes a `signingSecret`. **Save it immediately — it is shown only once.**

Use [`GET /listWebhookEndpoints`](/integration-guide/endpoints/webhooks/list-webhook-endpoints) to view all registered endpoints, and [`DELETE /deleteWebhookEndpoint`](/integration-guide/endpoints/webhooks/delete-webhook-endpoint) to remove one by `id`.

***

## Signature Verification

Every webhook delivery includes an `x-tga-signature` header containing an HMAC-SHA256 hex digest of the raw request body, signed with your endpoint's `signingSecret`.

**Always verify the signature before processing the payload.**

<CodeGroup>
  ```javascript Node.js theme={null}
  const crypto = require('crypto');

  function verifyWebhookSignature(payload, signature, signingSecret) {
    const expectedSig = crypto
      .createHmac('sha256', signingSecret)
      .update(payload, 'utf8')
      .digest('hex');
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSig)
    );
  }
  ```

  ```python Python theme={null}
  import hmac
  import hashlib

  def verify_webhook_signature(payload: bytes, signature: str, signing_secret: str) -> bool:
      expected = hmac.new(
          signing_secret.encode('utf-8'),
          payload,
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(signature, expected)
  ```
</CodeGroup>

<Warning>
  Pass the **raw request body bytes** to the verification function — do not parse JSON first. Any whitespace normalization will break the signature check.
</Warning>

***

## Delivery Guarantees & Idempotency

Webhooks are delivered **at least once**. The same event may be delivered more than once in rare cases (e.g., network failure after a successful delivery). Design your handler to be idempotent.

Each event payload includes a unique `eventId`. Use it as an idempotency key to deduplicate processing:

```json theme={null}
{
  "eventId": "evt_01HZ9X...",
  "eventType": "payroll_run.completed",
  "occurredAt": "2025-04-07T10:23:45Z",
  "data": { ... }
}
```

***

## Retry Logic

If your endpoint returns a non-`2xx` status or times out, Toku retries the delivery up to **3 times** with exponential backoff:

| Attempt   | Delay before retry |
| --------- | ------------------ |
| 1st retry | 1 second           |
| 2nd retry | 2 seconds          |
| 3rd retry | 4 seconds          |

Each attempt has a **10-second timeout**. After 3 failed retries the delivery is marked `failed` and no further attempts are made.

***

## Delivery Log

Use [`GET /listWebhookDeliveries`](/integration-guide/endpoints/webhooks/list-webhook-deliveries) with an `endpointId` to inspect delivery history for a specific endpoint — including status, response code, and timestamps for each attempt. This is the primary tool for debugging missed or failed deliveries.

***

## Event Type Reference

<Note>
  Events marked **TGA** are emitted only for Token Grant Administration workflows. Events marked **Payroll / EOR** are emitted for payroll runs and employer-of-record workflows.
</Note>

| Event                               | Domain        | When it fires                          |
| ----------------------------------- | ------------- | -------------------------------------- |
| `grant.created`                     | TGA           | A new token grant is created           |
| `grant.terminated`                  | TGA           | A grant is terminated                  |
| `grant.termination_reverted`        | TGA           | A grant termination is reversed        |
| `distribution.schedule_approved`    | TGA           | A distribution schedule is approved    |
| `distribution.settlement_completed` | TGA           | A distribution settlement is completed |
| `employee.onboarded`                | Payroll / EOR | An employee completes onboarding       |
| `employee.offboarded`               | Payroll / EOR | An employee is offboarded              |
| `payroll_run.created`               | Payroll       | A payroll run is created               |
| `payroll_run.approved`              | Payroll       | A payroll run is approved              |
| `payroll_run.completed`             | Payroll       | A payroll run finishes processing      |
| `payslip.generated`                 | Payroll       | A payslip is generated for an employee |
| `payment.initiated`                 | Payroll / EOR | A payment is initiated                 |
| `payment.completed`                 | Payroll / EOR | A payment is confirmed complete        |
| `contractor.invoice_submitted`      | Payroll       | A contractor submits an invoice        |
| `time_off.requested`                | Payroll / EOR | An employee requests time off          |
| `time_off.status_changed`           | Payroll / EOR | A time-off request status changes      |


# Integration Guide
Source: https://docs.toku.com/integration-guide/overview

Embed Toku's payroll, EOR, and stablecoin payment platform into your product

Toku's partner API lets your platform embed payroll, EOR, and stablecoin payment capabilities without building compliance infrastructure. Use this guide to connect your system to Toku's six core domains.

## Domain Guides

<CardGroup>
  <Card title="Authentication" icon="key" href="/integration-guide/guides/authentication">
    Obtain scoped API tokens and manage the token lifecycle
  </Card>

  <Card title="Payroll" icon="money-bill" href="/integration-guide/guides/payroll">
    Create payroll runs, validate, approve, and track disbursement
  </Card>

  <Card title="Employer of Record" icon="building" href="/integration-guide/guides/eor">
    Onboard EOR employees, manage profiles and onboarding progress
  </Card>

  <Card title="Payslips" icon="file-invoice" href="/integration-guide/guides/payslips">
    Generate, upload, and retrieve payslips with presigned download URLs
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration-guide/guides/webhooks">
    Subscribe to real-time events with HMAC-signed HTTPS delivery
  </Card>

  <Card title="Stablecoin Funding" icon="coins" href="/integration-guide/guides/stablecoin-funding">
    Pre-fund payroll with on-chain stablecoin transfers
  </Card>
</CardGroup>

## Integration Options

Toku supports three integration patterns depending on how deeply you want to embed its capabilities:

* **Embedded iframe**: Render Toku's hosted UI inside your product via iframe. Minimal engineering effort — drop in a frame and let Toku handle the UI.
* **SSO redirect**: Redirect authenticated users to Toku's portal using SSO. Users experience Toku's full interface under your authentication context.
* **Headless API**: Call Toku APIs directly and build your own UI. Full control over the user experience.

<Note>Use the headless API pattern when your platform needs full control over payroll and EOR UI while calling Toku APIs directly.</Note>

## Getting Started

<Steps>
  <Step title="Contact Toku">
    Request partner access to provision your organization and receive API credentials.
  </Step>

  <Step title="Create an API token">
    Call `POST /createUserAPIToken` with your organization credentials to get a scoped bearer token.
  </Step>

  <Step title="Configure webhooks">
    Register your HTTPS endpoint to receive real-time events for payroll, EOR, and payslip updates.
  </Step>

  <Step title="Run a test payroll">
    Create a draft payroll run with test employees to verify your integration end-to-end.
  </Step>

  <Step title="Go live">
    Switch to production credentials and begin processing real payroll runs.
  </Step>
</Steps>

## Quick Reference

| Domain             | What it covers                                     | Guide                                                            |
| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------- |
| Authentication     | API token creation and refresh                     | [Auth Guide](/integration-guide/guides/authentication)           |
| Payroll            | Payroll run lifecycle: create → approve → disburse | [Payroll Guide](/integration-guide/guides/payroll)               |
| Employer of Record | Employee onboarding, contracts, profile management | [EOR Guide](/integration-guide/guides/eor)                       |
| Payslips           | Payslip generation, upload, and download           | [Payslips Guide](/integration-guide/guides/payslips)             |
| Webhooks           | Event delivery, signing, retry logic               | [Webhooks Guide](/integration-guide/guides/webhooks)             |
| Stablecoin Funding | On-chain funding and settlement for payroll        | [Stablecoin Guide](/integration-guide/guides/stablecoin-funding) |

## Rate Limits

All API endpoints are rate-limited to 100 requests per minute per IP address. Requests that exceed this limit receive a `429 Too Many Requests` response. See [API Errors](/api/errors) for error response formats.

## Sandbox & Testing

<Info>Sandbox credentials are available on request. Contact Toku to provision a sandbox organization for integration testing before going live.</Info>

***

## Ready to use Toku?

<div>
  <div>
    <h3>Embed Toku into your product</h3>

    <p>
      Add payroll, EOR, and stablecoin payment workflows without building compliance infrastructure.
    </p>
  </div>

  <a href="https://www.toku.com/get-started">
    Sign up for Toku
  </a>
</div>


# Create API Token
Source: https://docs.toku.com/integration-guide/protected-links/create-api-token

Create an API token for integration access.

# Create API Token

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fintegration-guide%2Fendpoints%2Fauth%2Fcreate-api-token">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# Generate Auth Nonce
Source: https://docs.toku.com/integration-guide/protected-links/generate-auth-nonce

Generate an authentication nonce for your integration flow.

# Generate Auth Nonce

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fintegration-guide%2Fendpoints%2Fauth%2Fgenerate-auth-nonce">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# Refresh API Token
Source: https://docs.toku.com/integration-guide/protected-links/refresh-api-token

Refresh an API token used by your integration.

# Refresh API Token

This page is available to Toku customers and partners. Log in to continue, or sign up to connect with the Toku team.

<div>
  <div>
    <h3>Log in or sign up for access</h3>

    <p>
      If you already have access, log in to view this page. If you are new to Toku, reach out and we will help you get started.
    </p>
  </div>

  <div>
    <a href="https://docs.toku.com/login?redirect=%2Fintegration-guide%2Fendpoints%2Fauth%2Frefresh-api-token">
      Log In
    </a>

    <a href="https://www.toku.com/get-started">
      Sign Up
    </a>
  </div>
</div>


# ADP Integration
Source: https://docs.toku.com/integrations/adp

Run compliant stablecoin payroll alongside ADP Workforce Now with the Toku deduction

Toku integrates directly with **ADP Workforce Now** through **ADP API Central**, so your team can offer stablecoin payroll without changing how you run payroll today. ADP remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Link ADP to Toku with a dedicated API project created in ADP API Central.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your employee roster and payroll calendar from ADP automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is applied in ADP and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in ADP as one dedicated deduction line item on the employee's pay statement. Toku calculates the amount for each employee every pay period based on their election, and the deduction is applied through ADP's payroll APIs — no manual data entry, and no changes to your gross pay, taxes, or existing pay codes.

The deduction is configured once during implementation. Toku's team provides the exact ADP configuration as part of onboarding.

## What You'll Need

* Admin access to ADP Workforce Now and ADP API Central
* Admin access to your Toku account
* A short implementation session with the Toku team

## Setup Overview

<Steps>
  <Step title="Create an API project in ADP API Central">
    Your ADP administrator creates a dedicated project for Toku and generates secure API credentials and certificates.
  </Step>

  <Step title="Authorize the connection">
    Grant the Toku project the payroll and worker-data permissions it needs in ADP Workforce Now. Toku's implementation team provides the exact scope list.
  </Step>

  <Step title="Add the Toku deduction">
    Set up the dedicated Toku deduction code in ADP. Toku provides the configuration during onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → ADP**, enter your credentials, and connect. Toku validates the connection and begins syncing.
  </Step>
</Steps>

<Note>
  Detailed, step-by-step configuration guides (with screenshots) are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming payrolls and employee changes from ADP.
2. Toku calculates each employee's stablecoin amount and applies the Toku deduction to the pay run.
3. You run payroll in ADP exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Employee data** (roster, pay group, identifiers) syncs from ADP to Toku on a read-only basis.
* **Deduction data** is the only information Toku writes back to ADP.
* All credentials are encrypted at rest, and the connection uses ADP's certificate-based API authentication with least-privilege scopes.

## API Reference

How the integration works at the API level, with calls you can validate against ADP's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/adp/authentication">
    How Toku authenticates with ADP
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/adp/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/adp/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/adp/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Workday" icon="building" href="/integrations/workday">
    HCM and payroll integration
  </Card>

  <Card title="UKG" icon="building" href="/integrations/ukg">
    UKG Pro payroll integration
  </Card>
</CardGroup>


# ADP API Authentication
Source: https://docs.toku.com/integrations/adp/authentication

How Toku authenticates with the ADP API using OAuth 2.0 client credentials and mutual TLS

Toku connects to ADP Workforce Now using [ADP's OAuth 2.0 client credentials flow combined with mutual TLS](https://developers.adp.com/articles/general/introduction-mutual-ssl). Every call — token requests and API requests alike — is authenticated with both a client ID/secret and an ADP-issued X.509 client certificate.

## OAuth 2.0 + Mutual TLS Flow

<Steps>
  <Step title="Issue credentials">
    Your ADP administrator creates a dedicated API project for Toku in ADP API Central, which issues the client ID, client secret, and X.509 client certificate and key. (For ADP Marketplace subscriptions, credentials are granted through the Consent Manager instead.)
  </Step>

  <Step title="Request a token">
    Toku's backend presents the certificate and client credentials to ADP's token endpoint and receives a bearer access token.
  </Step>

  <Step title="Refresh">
    Tokens expire after 60 minutes. Toku requests a fresh token automatically before expiry — the connection stays live without manual intervention.
  </Step>
</Steps>

```bash theme={null}
# Token request (performed by Toku's backend)
curl --request POST \
  --url 'https://accounts.adp.com/auth/oauth/v2/token' \
  --cert toku.crt --key toku.key \
  --user '<client_id>:<client_secret>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'
```

A successful response:

```json theme={null}
{
  "access_token": "ba55dc8e-a532-4a9d-9c3c-4b7b6a9e2f10",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Authenticated API requests carry the bearer token **and** the same client certificate:

```bash theme={null}
curl "https://api.adp.com/hr/v2/workers" \
  --cert toku.crt --key toku.key \
  -H "Authorization: Bearer <access_token>"
```

## Mutual TLS Requirements

| Requirement        | Detail                                                                    |
| ------------------ | ------------------------------------------------------------------------- |
| Client certificate | ADP-issued X.509 certificate and private key, presented on **every** call |
| Hosts              | Required for both `accounts.adp.com` (tokens) and `api.adp.com` (APIs)    |
| TLS version        | TLS 1.2                                                                   |
| Token lifetime     | 3,600 seconds (60 minutes), auto-refreshed by Toku                        |

Because ADP validates the certificate on every request, a leaked client secret alone cannot access your data — the certificate is required as a second, independent factor.

## Environments

| Environment | Token endpoint                                    |
| ----------- | ------------------------------------------------- |
| US          | `https://accounts.adp.com/auth/oauth/v2/token`    |
| EU          | `https://accounts.eu.adp.com/auth/oauth/v2/token` |

<Note>
  Credentials and certificates are generated in your own ADP API Central project, so your ADP admin controls (and can revoke) Toku's access at any time. See [ADP's developer documentation](https://developers.adp.com/) and the [mutual TLS guide](https://developers.adp.com/articles/general/introduction-mutual-ssl) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="Employee Sync" icon="users" href="/integrations/adp/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/adp/payroll-sync">
    How Toku tracks pay cycles and payroll output
  </Card>
</CardGroup>


# Applying the Toku Deduction in ADP
Source: https://docs.toku.com/integrations/adp/deduction

How Toku applies the stablecoin deduction through ADP's Pay Data Input event API

Each pay cycle, Toku applies one dedicated deduction per participating worker, using ADP's Pay Data Input event API. This is the only write Toku performs against your ADP account.

## Endpoint

Before posting, Toku calls the API's meta endpoint — `GET /events/payroll/v1/pay-data-input.modify/meta` (filterable by `companyCode`/`fileNumber`) — to confirm the Toku deduction code is valid for your payroll group. It then submits a pay data batch:

```bash theme={null}
curl -X POST "https://api.adp.com/events/payroll/v1/pay-data-input.modify" \
  --cert toku.crt --key toku.key \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d @pay-data-batch.json
```

A trimmed request envelope:

```json theme={null}
{
  "events": [
    {
      "data": {
        "eventContext": {
          "payrollGroupCode": { "codeValue": "ABC" },
          "payrollProcessingJobID": "1234567"
        },
        "transform": {
          "payDataInput": {
            "payeePayInputs": [
              {
                "associateOID": "G3349PZGBADQY8H8",
                "payrollProfilePayInputs": [
                  {
                    "payrollFileNumber": "078765",
                    "payInputs": [
                      {
                        "deductionInputs": [
                          {
                            "deductionCode": { "codeValue": "TOKU" },
                            "deductionRate": { "rateValue": 250.00, "currencyCode": "USD" }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    }
  ]
}
```

The scope used is `/payroll/payrollManagement/payrollProcessing/payDataInputManagement/pay-data-input.modify`. See ADP's reference to validate the call: [Pay Data Input v1 API Explorer](https://developers.adp.com/apis/api-explorer/hcm-offrg-wfn/hcm-offrg-wfn-payroll-pay-data-input-v1-pay-data-input) and [ADP's sample payloads on GitHub](https://github.com/adpllc/marketplace-sample-payloads).

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each pay cycle.
* Toku recalculates and posts the deduction before each run, so one-off changes (bonuses, prorated periods, paused elections) are handled automatically.
* The line item appears on the worker's pay statement under the Toku deduction code configured during onboarding, so payslips stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                             |
| ---------------- | ------------------------------------------------------------------ |
| One line item    | Exactly one Toku deduction per participating worker per run        |
| No gross changes | Gross pay, taxes, and every other pay code are untouched           |
| Bounded amount   | The deduction is validated against pay before it is posted         |
| Reversible       | Removing a worker's election stops the deduction from the next run |

<Warning>
  ADP accepts a pay data batch only while the pay cycle is in the **Entering Payroll Information** or **Correcting Input** state, and a single invalid entry fails the entire multi-employee batch. Toku validates every entry against the meta endpoint before posting and retries per-employee, so one worker's issue never blocks the rest of the run.
</Warning>

## Reconciliation

After the payroll is processed, Toku reads the finalized payroll output, confirms each applied deduction, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/adp">
    Back to the ADP integration overview
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/adp/employee-sync">
    How Toku reads your worker roster
  </Card>
</CardGroup>


# ADP Employee Sync
Source: https://docs.toku.com/integrations/adp/employee-sync

How Toku syncs your worker roster from ADP Workforce Now

Toku keeps its worker roster in sync with ADP Workforce Now so stablecoin elections always map to the right person. Sync is read-only and runs automatically after every connection and on a rolling schedule.

## Endpoint

Toku reads workers through ADP's Workers v2 API, paginating with OData `$top`/`$skip`:

```bash theme={null}
curl "https://api.adp.com/hr/v2/workers?\$top=100&\$skip=0" \
  --cert toku.crt --key toku.key \
  -H "Authorization: Bearer <access_token>"
```

Workforce Now returns at most 100 workers per page (default 50); Toku pages with `$skip` until the `workers` array comes back empty. Individual records are available at `GET /hr/v2/workers/{aoid}`, and `$filter`/`$select` are supported for narrowing results. The scope used is `/hr/workerInformationManagement/workerManagement/workerProfileManagement/worker.read`.

A trimmed example response:

```json theme={null}
{
  "workers": [
    {
      "associateOID": "G3349PZGBADQY8H8",
      "workerID": { "idValue": "ADA001" },
      "person": {
        "legalName": { "formattedName": "Ada Lovelace" },
        "communication": {
          "emails": [{ "emailUri": "ada@yourcompany.com" }]
        }
      },
      "workAssignments": [
        {
          "positionID": "ABC0010078765",
          "assignmentStatus": { "statusCode": { "codeValue": "A" } },
          "payrollGroupCode": "ABC",
          "payrollFileNumber": "078765",
          "baseRemuneration": {
            "annualRateAmount": { "amountValue": 180000, "currencyCode": "USD" }
          }
        }
      ]
    }
  ]
}
```

See ADP's reference for the full schema: [Workers v2 API Explorer](https://developers.adp.com/apis/api-explorer/hcm-offrg-wfn/hcm-offrg-wfn-hr-workers-v2-workers).

## What Toku Reads

| Field                                   | Purpose                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `associateOID`                          | Stable identifier used to match the worker across systems and post deductions |
| `workAssignments[].positionID`          | Together with the Associate ID, identifies the worker for pay data input      |
| `person.legalName`, `emails[].emailUri` | Roster display and employee-portal invitations                                |
| `workAssignments[].assignmentStatus`    | Marks departed or inactive workers inactive in Toku                           |
| `payrollGroupCode`, `payrollFileNumber` | Routes the deduction to the right payroll group and file                      |
| `baseRemuneration`                      | Validates election limits against compensation                                |

## Sync Behavior

* **New workers** appear in Toku automatically after they're added in ADP Workforce Now.
* **Updates** (name, email, compensation, pay group) flow through on the next sync.
* **Inactive workers** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Employee sync never writes to ADP. Toku does not modify worker records, work assignments, or compensation.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/adp/payroll-sync">
    How Toku tracks pay cycles and payroll output
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/adp/deduction">
    How the deduction is applied via the Pay Data Input API
  </Card>
</CardGroup>


# ADP Payroll Sync
Source: https://docs.toku.com/integrations/adp/payroll-sync

How Toku reads payroll output from ADP Workforce Now

Toku tracks your ADP payroll calendar and reads finalized payroll output so the Toku deduction lands in the right pay cycle — and so on-chain delivery lines up with your pay date.

## Endpoint

Toku reads processed payroll results through ADP's Payroll Output API, filtered with OData to the runs it needs:

```bash theme={null}
curl "https://api.adp.com/payroll/v1/payroll-output?level=details&\$filter=payrollOutputs/payrollScheduleReference/payrollGroupCode eq 'ABC' and payrollOutputs/payrollScheduleReference/payrollYear eq 2026 and payrollOutputs/payrollScheduleReference/payrollWeekNumber eq 28&\$select=earnings,statutoryDeductions,nonStatutoryDeductions,memos" \
  --cert toku.crt --key toku.key \
  -H "Authorization: Bearer <access_token>"
```

Supported `$filter` dimensions include the `payrollScheduleReference` fields — `payrollYear`, `payrollWeekNumber`, and `payrollGroupCode` — or a specific `payrollProcessingJobID`. With `level=details`, `$select` narrows the payload to the sections Toku needs, such as `earnings`, `statutoryDeductions`, `nonStatutoryDeductions`, and `memos`.

A trimmed example response:

```json theme={null}
{
  "payrollOutputs": [
    {
      "payrollScheduleReference": {
        "payrollGroupCode": "ABC",
        "payrollYear": 2026,
        "payrollWeekNumber": 28
      },
      "payrollProcessingJobID": "1234567",
      "nonStatutoryDeductions": [
        {
          "deductionCode": { "codeValue": "TOKU" },
          "deductionAmount": { "amountValue": 250.00, "currencyCode": "USD" }
        }
      ]
    }
  ]
}
```

## What Toku Reads

| Field                                                                               | Purpose                                                        |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `payrollScheduleReference` (`payrollYear`, `payrollWeekNumber`, `payrollGroupCode`) | Ties each Toku pay cycle to the exact ADP pay run              |
| `payrollProcessingJobID`                                                            | Confirms which processing job produced the output              |
| `nonStatutoryDeductions`                                                            | Verifies the Toku deduction was applied at the expected amount |
| `earnings`, `statutoryDeductions`                                                   | Validates the election against actual pay before settlement    |

## Sync Behavior

* Upcoming pay cycles appear in the Toku dashboard based on your payroll group's schedule in ADP.
* When a run finishes processing, Toku reads the payroll output, reconciles the applied Toku deductions against it, and releases the corresponding stablecoin payments.
* Off-cycle runs are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payrolls in ADP — your team keeps full control of running payroll.
</Note>

## API Access

ADP gates the Payroll Output API behind partner-level approval. Toku holds this approval as an ADP integration partner, but the API must also be enabled for your ADP account — your ADP administrator requests enablement through ADP support during implementation. If payroll sync shows no data after connecting, this enablement is the most common cause. See [ADP's developer documentation](https://developers.adp.com/) for details.

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/adp/deduction">
    How the deduction is applied via the Pay Data Input API
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/adp/authentication">
    OAuth 2.0 client credentials and mutual TLS
  </Card>
</CardGroup>


# Deel Integration
Source: https://docs.toku.com/integrations/deel

Run compliant stablecoin payroll alongside Deel Global Payroll with the Toku deduction

Toku integrates with **Deel** through the Deel API, using scoped organization access that you authorize and control. Deel remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Authorize Toku's Deel connection for your organization with scoped API access.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your people roster, contracts, and payroll calendar from Deel automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Workers choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay cycle, a single Toku deduction is applied as an adjustment in Deel and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in Deel as one dedicated deduction line item on the worker's pay. Toku calculates the amount for each worker every pay cycle based on their election and applies it through Deel's adjustments API — no manual data entry, and no changes to your gross pay, taxes, or existing pay items.

The deduction is configured once during implementation. Toku's team provides the exact Deel configuration as part of onboarding.

## What You'll Need

* Admin access to your Deel organization
* Admin access to your Toku account
* A short implementation session with the Toku team

## Setup Overview

<Steps>
  <Step title="Authorize the connection">
    Your Deel administrator authorizes Toku's connection with read scopes for people, contracts, and payroll data, plus the single write scope Toku uses for adjustments.
  </Step>

  <Step title="Confirm the Toku deduction">
    Toku sets up the dedicated deduction category for participating workers as part of onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Deel** and complete the connection.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection, previews your worker roster, and begins syncing pay cycles.
  </Step>
</Steps>

<Note>
  Detailed configuration guides are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Cycle

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming pay cycles and worker changes from Deel.
2. Toku calculates each worker's stablecoin amount and applies the Toku deduction.
3. You run payroll in Deel exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **People, contract, and payroll data** syncs from Deel to Toku on a read-only basis.
* **Deduction adjustments** are the only information Toku writes back to Deel.
* Access uses scoped API tokens that you can revoke at any time, and all credentials are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Deel's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/deel/authentication">
    How Toku authenticates with Deel
  </Card>

  <Card title="People Sync" icon="users" href="/integrations/deel/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/deel/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/deel/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Rippling" icon="building" href="/integrations/rippling">
    Rippling payroll integration
  </Card>

  <Card title="Papaya Global" icon="building" href="/integrations/papaya-global">
    Papaya Global payroll integration
  </Card>
</CardGroup>


# Deel API Authentication
Source: https://docs.toku.com/integrations/deel/authentication

How Toku authenticates with the Deel API using OAuth 2.0 and granular scopes

Toku connects to Deel as an authorized [Deel App Store](https://developer.deel.com/docs/authentication) application using Deel's OAuth 2.0 flow. Your Deel admin authorizes the connection once — no API keys are copied or stored by your team.

## OAuth 2.0 Flow

<Steps>
  <Step title="Authorize">
    From the Toku dashboard, your admin is redirected to Deel's consent screen, which lists every scope Toku requests.
  </Step>

  <Step title="Exchange">
    Deel redirects back with an authorization code, which Toku's backend exchanges for an access token and refresh token.
  </Step>

  <Step title="Refresh">
    Access tokens live for 30 days. Toku rotates them automatically using Deel's single-use refresh tokens — the connection stays live without re-authorization.
  </Step>
</Steps>

Authenticated requests are sent over HTTPS and carry the token as a bearer header alongside Toku's client identifier — Deel requires both:

```bash theme={null}
curl "https://api.letsdeel.com/rest/v2/people" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>"
```

## Scopes

Deel enforces granular scopes in the `{resource}:read` / `{resource}:write` format. Toku requests the minimum set needed for stablecoin payroll:

| Scope               | Access | Used for                                |
| ------------------- | ------ | --------------------------------------- |
| `people:read`       | Read   | Worker roster sync and matching         |
| `worker:read`       | Read   | Worker-level detail for roster sync     |
| `contracts:read`    | Read   | Mapping each worker's active contract   |
| `adjustments:read`  | Read   | Verifying the Toku deduction each cycle |
| `adjustments:write` | Write  | Applying the Toku deduction             |

Any call outside these scopes is rejected by Deel. You can revoke Toku's authorization at any time from your Deel account, which immediately invalidates all tokens.

## Environments

| Environment                                  | Base URL                            |
| -------------------------------------------- | ----------------------------------- |
| Production                                   | `https://api.letsdeel.com/rest/v2`  |
| Sandbox (used during implementation testing) | `https://api-sandbox.demo.deel.com` |

<Note>
  Toku is integrated through the [Deel Developer Platform](https://developer.deel.com/) partner process as a Deel App Store application. See [Deel's authentication docs](https://developer.deel.com/docs/authentication) and [OAuth reference](https://developer.deel.com/api/oauth) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="People Sync" icon="users" href="/integrations/deel/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/deel/payroll-sync">
    How Toku tracks payroll cycles and payslips
  </Card>
</CardGroup>


# Applying the Toku Deduction in Deel
Source: https://docs.toku.com/integrations/deel/deduction

How Toku applies the stablecoin deduction through Deel's Adjustments API

Each payroll cycle, Toku applies one dedicated deduction per participating worker, using Deel's Adjustments API. This is the only write Toku performs against your Deel organization.

## Endpoint

```bash theme={null}
curl -X POST "https://api.letsdeel.com/rest/v2/adjustments" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "37nex2x",
    "amount": "-250.00",
    "description": "Toku Deduction",
    "adjustment_category_id": "<deduction_category_id>",
    "date_of_adjustment": "2026-07-15"
  }'
```

Deel's Adjustments API covers both Global Payroll and EOR, with categories for bonuses, allowances, and deductions — deductions are expressed as negative amounts. Toku targets the dedicated deduction category configured during onboarding, discovered via `GET /rest/v2/adjustments/categories`. See Deel's [Adjustments API announcement](https://www.deel.com/blog/new-adjustments-api/) and the Adjustments reference on the [Deel Developer Platform](https://developer.deel.com/) for the full request schema.

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each payroll cycle.
* Toku recalculates and updates the adjustment before each cycle, so one-off changes (bonuses, prorated periods, paused elections) are handled automatically.
* The line item appears on the worker's payslip with the Toku description, so payslips stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                               |
| ---------------- | -------------------------------------------------------------------- |
| One line item    | Exactly one Toku deduction per participating worker per cycle        |
| No gross changes | Gross pay, taxes, and every other pay item are untouched             |
| Bounded amount   | The deduction is validated against net pay before it is applied      |
| Reversible       | Removing a worker's election stops the deduction from the next cycle |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or existing adjustments in Deel — the `adjustments:write` scope is used only for the Toku deduction itself.
</Warning>

## Reconciliation

After the payroll cycle is finalized, Toku reads each applied adjustment back (`GET /rest/v2/adjustments/{id}` and `GET /rest/v2/contracts/{contract_id}/adjustments`), confirms it against the finalized run, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/deel">
    Back to the Deel integration overview
  </Card>

  <Card title="People Sync" icon="users" href="/integrations/deel/employee-sync">
    How Toku reads your worker roster
  </Card>
</CardGroup>


# Deel People Sync
Source: https://docs.toku.com/integrations/deel/employee-sync

How Toku syncs your worker roster from Deel

Toku keeps its worker roster in sync with Deel so stablecoin elections always map to the right person. Sync is read-only and runs automatically after every connection and on a rolling schedule.

## Endpoint

Toku reads workers through Deel's organization-wide people resource (scopes `people:read` and `worker:read`):

```bash theme={null}
curl "https://api.letsdeel.com/rest/v2/people" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>"
```

A trimmed example response:

```json theme={null}
{
  "data": [
    {
      "id": "9779767c-6044-48e0-bf68-aeb370b9a2e7",
      "full_name": "Ada Lovelace",
      "emails": [
        { "type": "work", "value": "ada@yourcompany.com" }
      ],
      "employments": [
        {
          "contract_id": "37nex2x",
          "state": "active",
          "hiring_type": "employee"
        }
      ]
    }
  ]
}
```

See Deel's reference for the full schema: [People](https://developer.deel.com/docs/people).

## What Toku Reads

| Field                       | Purpose                                                      |
| --------------------------- | ------------------------------------------------------------ |
| `id`                        | Stable identifier used to match the worker across systems    |
| `full_name`, `emails`       | Roster display and worker-portal invitations                 |
| `employments[].contract_id` | Ties each worker to the contract used for the Toku deduction |
| `employments[].state`       | Marks departed workers inactive in Toku                      |

<Note>
  In Deel, contracts are the central object for every engagement — each worker's active contract is what Toku targets when applying [the Toku deduction](/integrations/deel/deduction).
</Note>

## Sync Behavior

* **New workers** appear in Toku automatically once their Deel contract is active.
* **Updates** (name, email, contract changes) flow through on the next sync.
* **Departed workers** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  People sync never writes to Deel. Toku does not modify worker records, contracts, or onboarding state.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/deel/payroll-sync">
    How Toku tracks payroll cycles and payslips
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/deel/deduction">
    How the deduction is applied via the Deel API
  </Card>
</CardGroup>


# Deel Payroll Sync
Source: https://docs.toku.com/integrations/deel/payroll-sync

How Toku tracks payroll cycles and payslips in Deel

Toku tracks your Deel Global Payroll calendar so the Toku deduction is always applied to the right payroll cycle — and so on-chain delivery lines up with each cycle's finalization.

## Endpoints

Toku reads payroll data through Deel's Global Payroll (`gp/`) resources. Per-worker payslips:

```bash theme={null}
curl "https://api.letsdeel.com/rest/v2/gp/workers/<worker_id>/payslips" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>"
```

A trimmed example response:

```json theme={null}
{
  "data": [
    {
      "id": "f2a8c3de-91b4-4f2e-8a77-3d0c1c9e5b21",
      "from": "2026-07-01",
      "to": "2026-07-15",
      "status": "FINALIZED"
    }
  ]
}
```

For cycle-level verification, Toku reads the gross-to-net report for the payroll run:

```bash theme={null}
curl "https://api.letsdeel.com/rest/v2/gp/reports/<gp_report_id>/gross_to_net" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>"
```

A CSV export of the same report is available at `/gross_to_net/csv`. See Deel's reference for the full schemas: [Global Payroll introduction](https://developer.deel.com/api/global-payroll/introduction).

## What Toku Reads

| Data                           | Purpose                                                    |
| ------------------------------ | ---------------------------------------------------------- |
| Payslip period (`from` / `to`) | Determines which elections apply to the cycle              |
| Payslip `status`               | Confirms the cycle is finalized before Toku settles        |
| Gross-to-net report            | Verifies the Toku deduction line against the finalized run |

## Sync Behavior

* Upcoming payroll cycles appear in the Toku dashboard as Toku syncs them from Deel.
* Deel's webhook events — including **payroll cycle finalized** — notify Toku when a cycle closes, triggering reconciliation.
* Once a cycle is finalized, Toku verifies the applied deductions against the gross-to-net report and releases the corresponding stablecoin payments.

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payroll in Deel — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/deel/deduction">
    How the deduction is applied via the Deel API
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/deel/authentication">
    OAuth 2.0 scopes and token handling
  </Card>
</CardGroup>


# Gusto Integration
Source: https://docs.toku.com/integrations/gusto

Run compliant stablecoin payroll alongside Gusto with the Toku deduction

Toku integrates with **Gusto** through the Gusto API, connecting to your existing Gusto company with OAuth and granular, least-privilege scopes. Gusto remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Authorize Toku's Gusto connection for your company with a standard OAuth flow — no credentials to copy around.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your employee roster, pay schedules, and payrolls from Gusto automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is applied to the employee's pay in Gusto and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in Gusto as one dedicated deduction line item on the employee's pay. Toku calculates the amount for each employee every pay period based on their election and applies it through Gusto's employee-deduction APIs — no manual data entry, and no changes to your gross pay, taxes, or existing pay items.

The deduction is configured once during implementation. Toku's team provides the exact Gusto configuration as part of onboarding.

## What You'll Need

* Admin access to your Gusto company
* Admin access to your Toku account
* A short implementation session with the Toku team

## Setup Overview

<Steps>
  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Gusto** and sign in to Gusto to authorize the connection.
  </Step>

  <Step title="Approve access scopes">
    Review and approve the read scopes for employees and payrolls, plus the single write scope Toku uses to apply the deduction.
  </Step>

  <Step title="Confirm the Toku deduction">
    Toku sets up the dedicated deduction for participating employees as part of onboarding.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection, previews your employee roster, and begins syncing pay schedules and payrolls.
  </Step>
</Steps>

<Note>
  Detailed configuration guides are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming pay periods and employee changes from Gusto.
2. Toku calculates each employee's stablecoin amount and applies the Toku deduction.
3. You run payroll in Gusto exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Employee and payroll data** syncs from Gusto to Toku on a read-only basis.
* **Deduction data** is the only information Toku writes back to Gusto.
* Access uses OAuth with granular scopes — you can revoke it at any time from Gusto, and all tokens are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Gusto's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/gusto/authentication">
    How Toku authenticates with Gusto
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/gusto/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/gusto/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/gusto/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Rippling" icon="building" href="/integrations/rippling">
    Rippling payroll integration
  </Card>

  <Card title="Paychex" icon="building" href="/integrations/paychex">
    Paychex Flex payroll integration
  </Card>
</CardGroup>


# Gusto API Authentication
Source: https://docs.toku.com/integrations/gusto/authentication

How Toku authenticates with the Gusto API using OAuth 2.0 and granular scopes

Toku connects to Gusto as an authorized application using [Gusto's OAuth 2.0 flow](https://docs.gusto.com/app-integrations/docs/introduction). Your Gusto admin signs in once to authorize the connection — no API keys are copied or stored by your team.

## OAuth 2.0 Flow

<Steps>
  <Step title="Authorize">
    From the Toku dashboard, your admin is redirected to Gusto's consent screen, which lists every scope Toku requests.
  </Step>

  <Step title="Exchange">
    Gusto redirects back with an authorization code, which Toku's backend exchanges for an access token and refresh token.
  </Step>

  <Step title="Refresh">
    Access tokens are short-lived. Toku rotates them automatically using the refresh token — the connection stays live without re-authorization.
  </Step>
</Steps>

```bash theme={null}
# Token exchange (performed by Toku's backend)
curl -X POST https://api.gusto.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<toku_client_id>",
    "client_secret": "<toku_client_secret>",
    "code": "<authorization_code>",
    "grant_type": "authorization_code"
  }'
```

Authenticated requests carry the token as a bearer header and pin a dated API version:

```bash theme={null}
curl https://api.gusto.com/v1/companies/<company_id>/employees \
  -H "Authorization: Bearer <access_token>"
```

## Scopes

Gusto enforces granular, per-resource scopes. Toku requests the minimum set needed for stablecoin payroll:

| Scope                | Access | Used for                                |
| -------------------- | ------ | --------------------------------------- |
| `companies:read`     | Read   | Company and pay schedule details        |
| `employees:read`     | Read   | Employee roster sync and matching       |
| `payrolls:read`      | Read   | Pay period and payroll status sync      |
| `garnishments:read`  | Read   | Verifying the Toku deduction each cycle |
| `garnishments:write` | Write  | Applying the Toku deduction             |

Any call outside these scopes is rejected by Gusto. You can revoke Toku's authorization at any time from your Gusto account, which immediately invalidates all tokens.

## Environments

| Environment                               | Base URL                     |
| ----------------------------------------- | ---------------------------- |
| Production                                | `https://api.gusto.com`      |
| Demo (used during implementation testing) | `https://api.gusto-demo.com` |

<Note>
  Toku is integrated through the [Gusto Developer Portal](https://dev.gusto.com/) partner process, including Gusto's security review. See [Gusto's API documentation](https://docs.gusto.com/) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="Employee Sync" icon="users" href="/integrations/gusto/employee-sync">
    How Toku reads your employee roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/gusto/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>
</CardGroup>


# Applying the Toku Deduction in Gusto
Source: https://docs.toku.com/integrations/gusto/deduction

How Toku applies the stablecoin deduction through Gusto's employee deduction API

Each pay period, Toku applies one dedicated deduction per participating employee, using Gusto's employee deduction (garnishments) API. This is the only write Toku performs against your Gusto account.

## Endpoint

```bash theme={null}
curl -X POST "https://api.gusto.com/v1/employees/<employee_id>/garnishments" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250.00",
    "description": "Toku Deduction",
    "recurring": false,
    "court_ordered": false,
    "deduct_as_percentage": false,
    "active": true
  }'
```

Gusto models employee deductions and garnishments on the same resource — Toku uses it as a standard, non-court-ordered employee deduction. See Gusto's reference to validate the call: [Create a garnishment (employee deduction)](https://docs.gusto.com/app-integrations/reference/post-v1-employees-employee_id-garnishments).

## How the Amount Is Set

* The employee's stablecoin election in Toku determines the amount for each pay period.
* Toku recalculates and updates the deduction before each run, so one-off changes (bonuses, prorated periods, paused elections) are handled automatically.
* The line item appears on the employee's pay statement with the Toku description, so payslips stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                                |
| ---------------- | --------------------------------------------------------------------- |
| One line item    | Exactly one Toku deduction per participating employee per run         |
| No gross changes | Gross pay, taxes, and every other pay item are untouched              |
| Bounded amount   | The deduction is validated against net pay before it is applied       |
| Reversible       | Removing an employee's election stops the deduction from the next run |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or existing deductions in Gusto — the scope of write access is limited to the Toku deduction itself.
</Warning>

## Reconciliation

After the payroll is processed, Toku reads the finalized run, confirms each applied deduction, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/gusto">
    Back to the Gusto integration overview
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/gusto/employee-sync">
    How Toku reads your employee roster
  </Card>
</CardGroup>


# Gusto Employee Sync
Source: https://docs.toku.com/integrations/gusto/employee-sync

How Toku syncs your employee roster from Gusto

Toku keeps its employee roster in sync with Gusto so stablecoin elections always map to the right person. Sync is read-only and runs automatically after every connection and on a rolling schedule.

## Endpoint

Toku reads employees through Gusto's company-scoped employees resource:

```bash theme={null}
curl "https://api.gusto.com/v1/companies/<company_id>/employees" \
  -H "Authorization: Bearer <access_token>"
```

A trimmed example response:

```json theme={null}
[
  {
    "uuid": "9779767c-6044-48e0-bf68-aeb370b9a2e7",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@yourcompany.com",
    "company_uuid": "1b224dcb-4386-4b3e-b81f-9e6c18e0bcd3",
    "terminated": false,
    "onboarded": true,
    "jobs": [
      {
        "title": "Senior Engineer",
        "payment_unit": "Year",
        "rate": "180000.00"
      }
    ]
  }
]
```

See Gusto's reference for the full schema: [Get employees of a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-employees).

## What Toku Reads

| Field                              | Purpose                                                     |
| ---------------------------------- | ----------------------------------------------------------- |
| `uuid`                             | Stable identifier used to match the employee across systems |
| `first_name`, `last_name`, `email` | Roster display and employee-portal invitations              |
| `terminated`                       | Marks departed employees inactive in Toku                   |
| `jobs[].rate`, `payment_unit`      | Validates election limits against compensation              |

## Sync Behavior

* **New employees** appear in Toku automatically after they finish Gusto onboarding.
* **Updates** (name, email, compensation) flow through on the next sync.
* **Terminated employees** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Employee sync never writes to Gusto. Toku does not modify employee records, compensation, or onboarding state.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/gusto/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/gusto/deduction">
    How the deduction is applied via the Gusto API
  </Card>
</CardGroup>


# Gusto Payroll Sync
Source: https://docs.toku.com/integrations/gusto/payroll-sync

How Toku tracks pay periods and payroll status in Gusto

Toku tracks your Gusto payroll calendar so the Toku deduction is always applied to the right pay period — and so on-chain delivery lines up with your check date.

## Endpoint

Toku reads payrolls through Gusto's company payrolls resource, filtered to upcoming (unprocessed) runs:

```bash theme={null}
curl "https://api.gusto.com/v1/companies/<company_id>/payrolls?processing_statuses=unprocessed&include=totals" \
  -H "Authorization: Bearer <access_token>"
```

A trimmed example response:

```json theme={null}
[
  {
    "payroll_uuid": "f2a8c3de-91b4-4f2e-8a77-3d0c1c9e5b21",
    "pay_period": {
      "start_date": "2026-07-01",
      "end_date": "2026-07-15"
    },
    "check_date": "2026-07-20",
    "processed": false,
    "off_cycle": false
  }
]
```

See Gusto's reference for the full schema: [Get all payrolls for a company](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-payrolls).

## What Toku Reads

| Field                                | Purpose                                                 |
| ------------------------------------ | ------------------------------------------------------- |
| `payroll_uuid`                       | Ties each Toku pay cycle to the exact Gusto payroll run |
| `pay_period.start_date` / `end_date` | Determines which elections apply to the run             |
| `check_date`                         | Schedules on-chain stablecoin delivery                  |
| `processed`                          | Confirms the run is finalized before Toku settles       |

## Sync Behavior

* Upcoming pay periods appear in the Toku dashboard as soon as they exist in Gusto.
* When a payroll's status flips to processed, Toku reconciles the applied deductions against the run and releases the corresponding stablecoin payments.
* Off-cycle payrolls are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payrolls in Gusto — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/gusto/deduction">
    How the deduction is applied via the Gusto API
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/gusto/authentication">
    OAuth 2.0 scopes and token handling
  </Card>
</CardGroup>


# Papaya Global Integration
Source: https://docs.toku.com/integrations/papaya-global

Run compliant stablecoin payroll alongside Papaya Global with the Toku deduction

Toku integrates with **Papaya Global** through Papaya's APIs and Integration Center, exchanging payroll data securely across your payroll countries. Papaya remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Link Papaya Global to Toku with secure, per-environment API credentials.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your worker roster and payroll calendar from Papaya automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Workers choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each payroll cycle, a single Toku deduction is delivered as payroll input to Papaya and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in Papaya as one dedicated deduction line item in the payroll cycle. Toku calculates the amount for each worker every cycle based on their election and delivers it as payroll input through Papaya's Integration Center — no manual data entry, and no changes to your gross pay, taxes, or existing pay items.

The deduction is configured once during implementation, per payroll country. Toku's team provides the exact Papaya configuration as part of onboarding.

## What You'll Need

* Admin access to your Papaya Global account
* Admin access to your Toku account
* A short implementation session with the Toku and Papaya teams

## Setup Overview

<Steps>
  <Step title="Provision API access">
    Papaya issues secure API credentials for the Toku connection. Toku's implementation team coordinates this with Papaya's integration support.
  </Step>

  <Step title="Confirm the Toku deduction">
    Toku works with your payroll team to add the dedicated deduction to the relevant payroll calendars.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Papaya Global** and complete the connection.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection, previews your worker roster, and begins syncing payroll cycles.
  </Step>
</Steps>

<Note>
  Detailed configuration guides are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Payroll Cycle

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming payroll cycles and worker changes from Papaya.
2. Toku calculates each worker's stablecoin amount and delivers the Toku deduction as payroll input.
3. You run payroll in Papaya exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Worker and payroll data** syncs from Papaya to Toku on a read-only basis.
* **Deduction data** is the only information Toku sends back to Papaya.
* The connection uses token-based authentication over HTTPS with short-lived access tokens, and all credentials are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Papaya Global's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/papaya-global/authentication">
    How Toku authenticates with Papaya Global
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/papaya-global/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/papaya-global/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/papaya-global/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Deel" icon="building" href="/integrations/deel">
    Deel Global Payroll integration
  </Card>

  <Card title="Workday" icon="building" href="/integrations/workday">
    HCM and payroll integration
  </Card>
</CardGroup>


# Papaya Global API Authentication
Source: https://docs.toku.com/integrations/papaya-global/authentication

How Toku authenticates with Papaya Global using per-environment API credentials and short-lived JWT access tokens

Toku connects to Papaya Global's **Workforce OS** platform using API credentials that Papaya's integration support team provisions specifically for the Toku connection. Credentials are issued per environment — no shared or personal logins are used.

## Credentials

Papaya issues three values for each environment:

| Credential    | Purpose                                                       |
| ------------- | ------------------------------------------------------------- |
| API key       | Identifies the Toku integration to Papaya's API gateway       |
| Client ID     | Identifies the client application in the token exchange       |
| Client secret | Proves the client's identity — stored encrypted, never logged |

## Token Flow

<Steps>
  <Step title="Provision">
    Papaya integration support issues the API key, Client ID, and client secret for the Toku connection — one set per environment (sandbox and production).
  </Step>

  <Step title="Exchange">
    Toku's backend exchanges the client credentials at Papaya's token endpoint for a JWT access token.
  </Step>

  <Step title="Refresh">
    Access tokens are valid for 24 hours. Toku requests a fresh token automatically before expiry — the connection stays live without manual intervention.
  </Step>
</Steps>

```bash theme={null}
# Token exchange (performed by Toku's backend)
# The exact token endpoint path is provisioned by Papaya per environment
curl -X POST "https://api.papayaglobal.com/<token_endpoint>/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<toku_client_id>",
    "client_secret": "<toku_client_secret>"
  }'
```

Authenticated requests carry the JWT as a bearer header over HTTPS:

```bash theme={null}
curl "https://api.papayaglobal.com/<resource>" \
  -H "Authorization: Bearer <access_token>"
```

## Environments

| Environment | Used for                                        |
| ----------- | ----------------------------------------------- |
| Sandbox     | Implementation testing with non-production data |
| Production  | The live Toku connection                        |

Each environment has its own credential set, so sandbox testing can never touch production payroll data. Credentials can be revoked by Papaya at any time, which immediately invalidates all tokens.

<Note>
  Papaya's public developer documentation at [docs.papayaglobal.com](https://docs.papayaglobal.com) covers its Workforce Payments APIs. Worker and payroll data exchange for the Toku connection is arranged through Papaya's [Integration Center](https://www.papayaglobal.com/connectors/) and provisioned with Papaya's integration support during implementation.
</Note>

## Next

<CardGroup>
  <Card title="Worker Sync" icon="users" href="/integrations/papaya-global/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/papaya-global/payroll-sync">
    How Toku tracks payroll cycles and G2N data
  </Card>
</CardGroup>


# Applying the Toku Deduction in Papaya Global
Source: https://docs.toku.com/integrations/papaya-global/deduction

How Toku delivers the stablecoin deduction as payroll input through Papaya's Integration Center

Each payroll cycle, Toku delivers one dedicated deduction per participating worker as **payroll input** to the cycle, through the Integration Center feed provisioned for the Toku connection. This is the only data Toku sends back to Papaya.

## Payroll Input Record

Each deduction is one line in the payroll input for the cycle. The record below is the Toku ↔ Papaya data contract — not a public REST endpoint:

```json theme={null}
{
  "cycle_id": "PT-Monthly-2026-07",
  "worker_id": "PPY-104233",
  "deduction_code": "TOKU_STABLECOIN",
  "amount": "250.00",
  "currency": "EUR",
  "pay_period_start": "2026-07-01",
  "pay_period_end": "2026-07-31"
}
```

The deduction code is configured once per payroll country during onboarding, so the line item appears consistently on payslips across every country you run with Papaya. See [docs.papayaglobal.com](https://docs.papayaglobal.com) for Papaya's public developer documentation.

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each pay period.
* Toku refreshes the payroll input before each cycle's cutoff, so changes (updated elections, prorated periods, paused elections) are handled automatically.
* The line item appears on the worker's payslip under the configured Toku deduction code, so pay statements stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                               |
| ---------------- | -------------------------------------------------------------------- |
| One line item    | Exactly one Toku deduction per participating worker per cycle        |
| No gross changes | Gross pay, taxes, and every other pay item are untouched             |
| Bounded amount   | The deduction is validated against pay before it is delivered        |
| Reversible       | Removing a worker's election stops the deduction from the next cycle |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or existing deductions in Papaya — the Toku deduction line is the only payroll input Toku delivers.
</Warning>

## Reconciliation

After the cycle is finalized, Toku receives the gross-to-net (G2N) report data, confirms each applied deduction against it, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/papaya-global">
    Back to the Papaya Global integration overview
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/papaya-global/employee-sync">
    How Toku reads your worker roster
  </Card>
</CardGroup>


# Papaya Global Worker Sync
Source: https://docs.toku.com/integrations/papaya-global/employee-sync

How Toku syncs your worker roster from Papaya Global

Toku keeps its roster in sync with Papaya Global so stablecoin elections always map to the right person — whether they're an employee, an EOR worker, or a contractor. Sync is read-only and runs on a schedule agreed during implementation.

## Data Feed

Papaya provisions the worker data feed for the Toku connection through its **Integration Center** — the in-platform hub Papaya uses to exchange HR and payroll data via pre-built APIs, file-based exchange, and custom API development. There is no public REST endpoint to call; the feed is configured per customer during onboarding.

A trimmed example of the worker record in the Toku ↔ Papaya data contract:

```json theme={null}
{
  "worker_id": "PPY-104233",
  "full_name": "Ada Lovelace",
  "work_email": "ada@yourcompany.com",
  "country": "PT",
  "currency": "EUR",
  "pay_group": "PT-Monthly",
  "compensation": {
    "amount": "78000.00",
    "frequency": "annual"
  },
  "status": "active"
}
```

Papaya's public developer documentation lives at [docs.papayaglobal.com](https://docs.papayaglobal.com); the exact feed configuration for your account is confirmed with Papaya's integration support during implementation.

## What Toku Reads

| Field                     | Purpose                                                       |
| ------------------------- | ------------------------------------------------------------- |
| `worker_id`               | Stable identifier used to match the worker across systems     |
| `full_name`, `work_email` | Roster display and worker-portal invitations                  |
| `country`, `currency`     | Maps the worker to the right payroll country and pay currency |
| `pay_group`               | Ties the worker to the correct payroll calendar               |
| `compensation`            | Validates election limits against pay                         |
| `status`                  | Marks departed workers inactive in Toku                       |

## Sync Behavior

* **New workers** appear in Toku automatically once they're active in Papaya.
* **Updates** (name, email, compensation, pay group) flow through on the next scheduled sync.
* **Inactive or offboarded workers** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Worker sync never writes to Papaya. Toku does not modify worker records, compensation, or employment state — across all 160+ countries Papaya supports.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/papaya-global/payroll-sync">
    How Toku tracks payroll cycles and G2N data
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/papaya-global/deduction">
    How the deduction is delivered as payroll input
  </Card>
</CardGroup>


# Papaya Global Payroll Sync
Source: https://docs.toku.com/integrations/papaya-global/payroll-sync

How Toku tracks payroll cycles and gross-to-net data in Papaya Global

Toku tracks your Papaya payroll calendar so the Toku deduction is always delivered to the right payroll cycle — and so on-chain delivery lines up with each country's pay date.

## Data Feed

Payroll calendar and cycle data is exchanged through Papaya's **Integration Center**, using the feed provisioned for the Toku connection. Papaya also sends webhook notifications for cycle events, so Toku learns immediately when a cycle is finalized instead of waiting for the next scheduled sync.

A trimmed example of the payroll cycle record in the Toku ↔ Papaya data contract:

```json theme={null}
{
  "cycle_id": "PT-Monthly-2026-07",
  "pay_period_start": "2026-07-01",
  "pay_period_end": "2026-07-31",
  "pay_date": "2026-07-28",
  "status": "open"
}
```

Once a cycle is finalized, Toku receives the corresponding **gross-to-net (G2N) report** data — including per-worker gross and net amounts — through the same feed. See [docs.papayaglobal.com](https://docs.papayaglobal.com) for Papaya's public developer documentation; your feed configuration is confirmed during implementation.

## What Toku Reads

| Field                                 | Purpose                                                    |
| ------------------------------------- | ---------------------------------------------------------- |
| `cycle_id`                            | Ties each Toku pay cycle to the exact Papaya payroll cycle |
| `pay_period_start` / `pay_period_end` | Determines which elections apply to the cycle              |
| `pay_date`                            | Schedules on-chain stablecoin delivery                     |
| `status`                              | Gates deduction delivery (open) and settlement (finalized) |
| Per-worker gross / net (G2N)          | Reconciles applied deductions before funds move            |

## Sync Behavior

* Upcoming payroll cycles appear in the Toku dashboard as soon as they exist on the Papaya payroll calendar.
* While a cycle is open, Toku delivers the Toku deduction as payroll input ahead of the cutoff.
* When a cycle is finalized, a webhook notification triggers reconciliation: Toku checks the G2N report against the applied deductions and releases the corresponding stablecoin payments.
* Off-cycle runs are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never opens, calculates, or approves payroll cycles in Papaya — your team and Papaya's in-country partners (ICPs) keep full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/papaya-global/deduction">
    How the deduction is delivered as payroll input
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/papaya-global/authentication">
    Credentials, token exchange, and environments
  </Card>
</CardGroup>


# Paychex Integration
Source: https://docs.toku.com/integrations/paychex

Run compliant stablecoin payroll alongside Paychex Flex with the Toku deduction

Toku integrates with **Paychex Flex** through the Paychex APIs, using secure OAuth client credentials issued for your company. Paychex remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Authorize Toku's Paychex connection for your company with secure API credentials.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your worker roster and pay periods from Paychex Flex automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is applied as a pay component in Paychex and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in Paychex as one dedicated deduction on the employee's check. Toku calculates the amount for each employee every pay period based on their election and applies it through Paychex's pay component APIs before the check is processed — no manual data entry, and no changes to your gross pay, taxes, or existing pay components.

The deduction is configured once during implementation. Toku's team provides the exact Paychex configuration as part of onboarding.

## What You'll Need

* Admin access to your Paychex Flex account
* Admin access to your Toku account
* A short implementation session with the Toku team

## Setup Overview

<Steps>
  <Step title="Authorize the connection">
    Your Paychex administrator authorizes Toku's access to your company data. Toku's implementation team coordinates the API access with Paychex.
  </Step>

  <Step title="Confirm the Toku deduction">
    Toku sets up the dedicated deduction pay component for participating employees as part of onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Paychex** and complete the connection.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection, previews your worker roster, and begins syncing pay periods.
  </Step>
</Steps>

<Note>
  Detailed configuration guides are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming pay periods and worker changes from Paychex.
2. Toku calculates each employee's stablecoin amount and applies the Toku deduction before checks are processed.
3. You run payroll in Paychex exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Worker and pay period data** syncs from Paychex to Toku on a read-only basis.
* **Deduction data** is the only information Toku writes back to Paychex.
* The connection uses OAuth 2.0 with company-scoped access, and all credentials are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Paychex's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/paychex/authentication">
    How Toku authenticates with Paychex
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/paychex/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/paychex/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/paychex/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Gusto" icon="building" href="/integrations/gusto">
    Gusto payroll integration
  </Card>

  <Card title="ADP" icon="building" href="/integrations/adp">
    ADP Workforce Now payroll integration
  </Card>
</CardGroup>


# Paychex API Authentication
Source: https://docs.toku.com/integrations/paychex/authentication

How Toku authenticates with the Paychex APIs using OAuth 2.0 client credentials

Toku connects to the [Paychex APIs](https://developer.paychex.com/) using OAuth 2.0 client credentials issued through the Paychex developer program. Access is provisioned per company — there are no self-serve API keys, and none are copied or stored by your team.

## OAuth 2.0 Client Credentials Flow

<Steps>
  <Step title="Provision">
    Toku's connection is provisioned through the [Paychex partner program](https://developer.paychex.com/partner) and authorized for your company by your Paychex administrator during onboarding.
  </Step>

  <Step title="Authenticate">
    Toku's backend exchanges its client ID and secret for a bearer access token using the client credentials grant.
  </Step>

  <Step title="Renew">
    Access tokens are short-lived. There is no refresh-token flow — Toku simply re-acquires a token automatically when one expires, so the connection stays live without any action from your team.
  </Step>
</Steps>

```bash theme={null}
# Token request (performed by Toku's backend)
curl -X POST https://api.paychex.com/auth/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<toku_client_id>" \
  -d "client_secret=<toku_client_secret>"
```

Authenticated requests carry the token as a bearer header:

```bash theme={null}
curl https://api.paychex.com/companies/<company_id>/workers \
  -H "Authorization: Bearer <access_token>"
```

## Access & Provisioning

Paychex provisions API access through its developer and partner program rather than granular self-service scopes:

| Aspect       | Detail                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------ |
| Access model | Partner credentials provisioned by Paychex, authorized per company                         |
| Data scope   | Company-scoped — Toku can only read data for companies that have authorized the connection |
| Reads        | Workers, pay periods, and checks                                                           |
| Writes       | Worker pay components (the Toku deduction only)                                            |

Your Paychex administrator can revoke Toku's company authorization at any time, which immediately cuts off API access.

## Environments

| Environment | Base URL                  |
| ----------- | ------------------------- |
| Production  | `https://api.paychex.com` |

<Note>
  Toku is integrated through the [Paychex Developer Program](https://developer.paychex.com/) and listed in the [Paychex Marketplace](https://marketplace.paychex.com/). See the [Paychex API Developer Center](https://developer.paychex.com/) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="Worker Sync" icon="users" href="/integrations/paychex/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/paychex/payroll-sync">
    How Toku tracks pay periods and checks
  </Card>
</CardGroup>


# Applying the Toku Deduction in Paychex
Source: https://docs.toku.com/integrations/paychex/deduction

How Toku applies the stablecoin deduction through Paychex worker pay components

Each pay period, Toku applies one dedicated deduction per participating worker, using Paychex **pay components** — the resource Paychex uses for both earnings and deductions. This is the only write Toku performs against your Paychex account.

## Resource

Toku manages the deduction as a recurring, effective-dated pay component on the worker:

```
/workers/{workerId}/paycomponents
```

A minimal, illustrative request body:

```json theme={null}
{
  "componentId": "<toku_deduction_component_id>",
  "effectDate": "2026-07-01",
  "value": "250.00"
}
```

For one-off adjustments, Paychex also supports adding pay component lines directly to a worker's **unprocessed check** for the current period; once a check is processed, its pay components can no longer be changed.

<Note>
  The full pay component payload reference is available in the partner-gated [Paychex API reference](https://developer.paychex.com/) — the JSON above is illustrative, not the complete schema. The deduction pay component itself is configured once during implementation with the Toku team.
</Note>

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each pay period.
* Toku updates the pay component before checks are processed each cycle, so election changes take effect on the next run automatically.
* The line item appears as a dedicated Toku deduction on the worker's check, so pay statements stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                                |
| ---------------- | --------------------------------------------------------------------- |
| One line item    | Exactly one Toku deduction per participating worker per pay period    |
| No gross changes | Gross pay, taxes, and every other pay component are untouched         |
| Unprocessed only | Toku only writes to pay components before the check is processed      |
| Reversible       | Removing a worker's election stops the deduction from the next period |

<Warning>
  Toku never modifies compensation, tax withholding, direct deposit, or existing pay components in Paychex — the scope of write access is limited to the Toku deduction itself.
</Warning>

## Reconciliation

After checks are processed, Toku reads the finalized checks, confirms each applied deduction, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/paychex">
    Back to the Paychex integration overview
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/paychex/employee-sync">
    How Toku reads your worker roster
  </Card>
</CardGroup>


# Paychex Worker Sync
Source: https://docs.toku.com/integrations/paychex/employee-sync

How Toku syncs your worker roster from Paychex Flex

Toku keeps its roster in sync with Paychex Flex so stablecoin elections always map to the right person. Paychex models both W-2 employees and 1099 contractors as **workers**, and Toku syncs both. Sync is read-only and runs automatically after every connection and on a rolling schedule.

## Endpoint

Toku reads workers through Paychex's company-scoped workers resource:

```bash theme={null}
curl "https://api.paychex.com/companies/<company_id>/workers" \
  -H "Authorization: Bearer <access_token>"
```

A trimmed, representative example response:

```json theme={null}
{
  "content": [
    {
      "workerId": "00Z5V9BJTLXCR27S3RS4",
      "workerType": "EMPLOYEE",
      "name": {
        "givenName": "Ada",
        "familyName": "Lovelace"
      },
      "currentStatus": {
        "statusType": "ACTIVE"
      }
    },
    {
      "workerId": "00Z5V9CQ8MXDN41T7UW2",
      "workerType": "INDEPENDENT_CONTRACTOR",
      "name": {
        "givenName": "Grace",
        "familyName": "Hopper"
      },
      "currentStatus": {
        "statusType": "ACTIVE"
      }
    }
  ]
}
```

See Paychex's reference for the full schema: [Worker resource](https://developer.paychex.com/resources/worker).

## What Toku Reads

| Field           | Purpose                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------- |
| `workerId`      | Stable identifier used to match the worker across systems                                 |
| `workerType`    | Distinguishes W-2 employees (`EMPLOYEE`) from 1099 contractors (`INDEPENDENT_CONTRACTOR`) |
| `name`          | Roster display and worker-portal invitations                                              |
| `currentStatus` | Marks departed workers inactive in Toku                                                   |

Paychex exposes worker sub-resources for compensation, communications, and direct deposit; Toku reads only what it needs to validate elections and display the roster.

## Sync Behavior

* **New workers** appear in Toku automatically once they exist in Paychex Flex.
* **Updates** (name, status, worker type) flow through on the next sync.
* **Inactive workers** are marked inactive in Toku and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Worker sync never writes to Paychex. Toku does not modify worker records, compensation, communications, or direct deposit details.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/paychex/payroll-sync">
    How Toku tracks pay periods and checks
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/paychex/deduction">
    How the deduction is applied via pay components
  </Card>
</CardGroup>


# Paychex Payroll Sync
Source: https://docs.toku.com/integrations/paychex/payroll-sync

How Toku tracks pay periods and checks in Paychex Flex

Toku tracks your Paychex payroll calendar so the Toku deduction is always applied to the right pay period — and so on-chain delivery lines up with your check date.

## Pay Periods

Toku reads pay periods through Paychex's company-scoped pay periods resource, filterable by date range and status:

```bash theme={null}
curl "https://api.paychex.com/companies/<company_id>/payperiods" \
  -H "Authorization: Bearer <access_token>"
```

A trimmed, representative example response:

```json theme={null}
{
  "content": [
    {
      "payPeriodId": "00Z5V9E2NKXFP83U1WY6",
      "frequency": "SEMI_MONTHLY",
      "status": "ENTRY",
      "startDate": "2026-07-01",
      "endDate": "2026-07-15",
      "submitByDate": "2026-07-17",
      "checkDate": "2026-07-20"
    }
  ]
}
```

Individual periods are available at `/payperiods/{payperiodId}`. See the [Paychex API Developer Center](https://developer.paychex.com/) for the full schema.

## Checks

Within each pay period, Toku reads the company's checks to confirm the Toku deduction landed on the right ones:

```bash theme={null}
curl "https://api.paychex.com/companies/<company_id>/checks" \
  -H "Authorization: Bearer <access_token>"
```

Checks are either **unprocessed** (pay components can still be added, updated, or removed) or **processed** (finalized). Toku only ever writes to unprocessed checks, and uses processed checks for reconciliation.

## What Toku Reads

| Field                   | Purpose                                                    |
| ----------------------- | ---------------------------------------------------------- |
| `payPeriodId`           | Ties each Toku pay cycle to the exact Paychex pay period   |
| `startDate` / `endDate` | Determines which elections apply to the period             |
| `checkDate`             | Schedules on-chain stablecoin delivery                     |
| `submitByDate`          | Ensures the deduction is applied before payroll submission |
| `status`                | Confirms the period is finalized before Toku settles       |

## Sync Behavior

* Upcoming pay periods appear in the Toku dashboard as soon as they exist in Paychex.
* When a period's checks are processed, Toku reconciles the applied deductions against them and releases the corresponding stablecoin payments.

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payroll in Paychex — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/paychex/deduction">
    How the deduction is applied via pay components
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/paychex/authentication">
    OAuth 2.0 client credentials and token handling
  </Card>
</CardGroup>


# Rippling Integration
Source: https://docs.toku.com/integrations/rippling

Run compliant stablecoin payroll alongside Rippling with the Toku deduction

Toku integrates with **Rippling** through the Rippling API, using an OAuth connection with scopes your admin approves at install time. Rippling remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Authorize Toku's Rippling connection for your company with a standard OAuth install — no credentials to copy around.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your worker roster and payroll runs from Rippling automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is reflected as a pay input on the payroll run and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in Rippling as one dedicated line item on the worker's pay. Toku calculates the amount for each worker every pay period based on their election and applies it as a pay input through Rippling's payroll APIs — no manual data entry, and no changes to your gross pay, taxes, or existing pay items.

The deduction is configured once during implementation. Toku's team provides the exact Rippling configuration as part of onboarding.

## What You'll Need

* Admin access to your Rippling account
* Admin access to your Toku account
* A short implementation session with the Toku team

## Setup Overview

<Steps>
  <Step title="Authorize the connection">
    Your Rippling administrator installs and approves Toku's connection, reviewing the read scopes for workers and payroll plus the single write scope Toku uses for pay inputs.
  </Step>

  <Step title="Confirm the Toku deduction">
    Toku sets up the dedicated pay line item for participating workers as part of onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Rippling** and complete the connection.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection, previews your worker roster, and begins syncing payroll runs.
  </Step>
</Steps>

<Note>
  Detailed configuration guides are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming payroll runs and worker changes from Rippling.
2. Toku calculates each worker's stablecoin amount and applies the Toku deduction to the pay run.
3. You run payroll in Rippling exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Worker and payroll data** syncs from Rippling to Toku on a read-only basis.
* **The Toku pay input** is the only information Toku writes back to Rippling.
* Access uses OAuth with admin-approved, per-company scopes — you can revoke it at any time from Rippling, and all tokens are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Rippling's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/rippling/authentication">
    How Toku authenticates with Rippling
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/rippling/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/rippling/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/rippling/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="Deel" icon="building" href="/integrations/deel">
    Deel Global Payroll integration
  </Card>

  <Card title="Gusto" icon="building" href="/integrations/gusto">
    Gusto payroll integration
  </Card>
</CardGroup>


# Rippling API Authentication
Source: https://docs.toku.com/integrations/rippling/authentication

How Toku authenticates with the Rippling REST API using OAuth 2.0 and admin-approved scopes

Toku connects to Rippling as a partner app built in the [Rippling Developer Portal](https://developer.rippling.com/documentation/developer-portal) and published as an App Listing in the Rippling App Shop. Your Rippling admin installs the app once and consents to the declared scopes — no API keys are copied or stored by your team.

## OAuth 2.0 Flow

Rippling uses the standard [OAuth 2.0 authorization-code flow](https://developer.rippling.com/documentation/developer-portal/v2-guides/installation):

<Steps>
  <Step title="Install">
    Your admin installs Toku from the Rippling App Shop and reviews the consent screen, which lists every scope declared on Toku's App Listing.
  </Step>

  <Step title="Exchange">
    Rippling redirects back to Toku with `?code=...`, an authorization code that Toku's backend exchanges for an access token and refresh token.
  </Step>

  <Step title="Refresh">
    Tokens are issued per-company. Toku rotates access tokens automatically using the refresh token — the connection stays live without re-authorization.
  </Step>
</Steps>

Authenticated requests to the Rippling REST API carry the token as a bearer header:

```bash theme={null}
curl "https://rest.ripplingapis.com/workers" \
  -H "Authorization: Bearer <access_token>"
```

## Scopes

Rippling scopes follow a per-resource read/write convention: each scope is declared on Toku's App Listing, shown to your admin at install time, and gates access to the matching endpoints. Toku requests the minimum set needed for stablecoin payroll:

| Resource               | Access | Used for                                     |
| ---------------------- | ------ | -------------------------------------------- |
| Workers                | Read   | Worker roster sync and matching              |
| Compensations          | Read   | Validating election limits against pay       |
| Payroll runs & records | Read   | Pay period and payroll status sync           |
| Earnings inputs        | Write  | Reflecting the Toku pay line item on the run |

Any call outside the approved scopes is rejected by Rippling. You can revoke Toku's installation at any time from your Rippling account, which invalidates the company's tokens.

## Environments

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Production  | `https://rest.ripplingapis.com` |

<Note>
  Toku is integrated through Rippling's partner app process in the [Developer Portal](https://developer.rippling.com/documentation/developer-portal). See the [Rippling REST API documentation](https://developer.rippling.com/documentation/rest-api) to validate any of the calls referenced in this section — note that Rippling's endpoint-level reference requires a Rippling developer sign-in.
</Note>

## Next

<CardGroup>
  <Card title="Worker Sync" icon="users" href="/integrations/rippling/employee-sync">
    How Toku reads your worker roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/rippling/payroll-sync">
    How Toku tracks payroll runs and pay periods
  </Card>
</CardGroup>


# Applying the Toku Deduction in Rippling
Source: https://docs.toku.com/integrations/rippling/deduction

How the Toku stablecoin line item is reflected on the pay run through Rippling's pay-input APIs

Each pay period, exactly one Toku line item is reflected per participating worker, using Rippling's pay-input APIs. This is the only write Toku performs against your Rippling account.

## How It's Applied

Rippling's documented write path for adding pay line items to a payroll run is its **earnings inputs** operations — list, create, and delete earnings inputs, plus **List earning types**. Rippling does not expose a public generic "create deduction" REST endpoint (deductions appear read-only inside worker payroll records), so the Toku line item is reflected on the pay run through these pay-input operations, using a dedicated earning type configured with Rippling during implementation.

Toku first matches the participating worker through the workers resource:

```bash theme={null}
curl "https://rest.ripplingapis.com/workers" \
  -H "Authorization: Bearer <access_token>"
```

Then, before each run, Toku creates the worker's earnings input on the payroll run via the **create earnings input** operation. Rippling's endpoint-level reference for the earnings-input operations requires a Rippling developer sign-in — see the [REST API documentation](https://developer.rippling.com/documentation/rest-api) to validate them.

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each pay period.
* Toku recalculates and updates the pay input before each run, so one-off changes (paused elections, prorated periods) are handled automatically.
* The line item appears on the worker's pay with the Toku-dedicated earning type, so pay statements stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                                |
| ---------------- | --------------------------------------------------------------------- |
| One line item    | Exactly one Toku pay input per participating worker per run           |
| No gross changes | Gross pay, taxes, and every other pay item are untouched              |
| Bounded amount   | The amount is validated against the worker's pay before it is applied |
| Reversible       | Removing a worker's election stops the line item from the next run    |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or existing pay items in Rippling — the scope of write access is limited to the Toku line item itself.
</Warning>

## Reconciliation

After the payroll run is finalized, Toku reads the worker payroll records for the run, confirms each applied Toku line item, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/rippling">
    Back to the Rippling integration overview
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/rippling/employee-sync">
    How Toku reads your worker roster
  </Card>
</CardGroup>


# Rippling Worker Sync
Source: https://docs.toku.com/integrations/rippling/employee-sync

How Toku syncs your worker roster from Rippling

Toku keeps its roster in sync with Rippling so stablecoin elections always map to the right person. Rippling models each person's HR and employment profile as a **worker**. Sync is read-only and runs automatically after every connection and on a rolling schedule.

## Endpoint

Toku reads workers through Rippling's workers resource:

```bash theme={null}
curl "https://rest.ripplingapis.com/workers" \
  -H "Authorization: Bearer <access_token>"
```

Individual workers are readable at `GET /workers/{id}`. A trimmed, representative example response:

```json theme={null}
{
  "results": [
    {
      "id": "wrk_3f8a1c9e5b21",
      "legal_name": {
        "given_name": "Ada",
        "family_name": "Lovelace"
      },
      "preferred_name": "Ada",
      "work_email": "ada@yourcompany.com",
      "status": "ACTIVE"
    }
  ]
}
```

This is representative, not an exhaustive schema. See Rippling's reference for the full shape: [List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers) (endpoint-level details require a Rippling developer sign-in).

## What Toku Reads

| Field                                                | Purpose                                                   |
| ---------------------------------------------------- | --------------------------------------------------------- |
| `id`                                                 | Stable identifier used to match the worker across systems |
| Legal and preferred name, work email                 | Roster display and worker-portal invitations              |
| `status`                                             | Marks departed workers inactive in Toku                   |
| Compensation (via Rippling's compensations resource) | Validates election limits against pay                     |

## Sync Behavior

* **New workers** appear in Toku automatically once they exist in Rippling.
* **Updates** (name, email, compensation) flow through on the next sync.
* **Departed workers** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Worker sync never writes to Rippling. Toku does not modify worker records, compensation, or employment state.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/rippling/payroll-sync">
    How Toku tracks payroll runs and pay periods
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/rippling/deduction">
    How the Toku line item is reflected on the pay run
  </Card>
</CardGroup>


# Rippling Payroll Sync
Source: https://docs.toku.com/integrations/rippling/payroll-sync

How Toku tracks payroll runs and pay periods in Rippling

Toku tracks your Rippling payroll calendar so the Toku line item is always applied to the right payroll run — and so on-chain delivery lines up with your pay date.

## Operations

Toku uses two documented, read-oriented operations from the [Rippling REST API](https://developer.rippling.com/documentation/rest-api):

| Operation                       | What it returns                                                                                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **List payroll runs**           | Payroll runs with their pay periods (`PayrollRun`, `PayrollRunPayPeriod` schemas)                                                                                   |
| **List worker payroll records** | Per-worker line items on a run (`WorkerPayrollRecord`, containing `WorkerPayrollEarning`, `WorkerPayrollDeduction`, `WorkerPayrollGarnishment`, `WorkerPayrollTax`) |

A trimmed, representative payroll run shape:

```json theme={null}
{
  "results": [
    {
      "id": "prun_8a77c3de91b4",
      "pay_period": {
        "start_date": "2026-07-01",
        "end_date": "2026-07-15"
      },
      "status": "FINALIZED"
    }
  ]
}
```

This is representative, not an exhaustive schema. Rippling's endpoint-level reference for these operations requires a Rippling developer sign-in — see the [REST API documentation](https://developer.rippling.com/documentation/rest-api) to validate them.

## What Toku Reads

| Data                         | Purpose                                                         |
| ---------------------------- | --------------------------------------------------------------- |
| Payroll run `id`             | Ties each Toku pay cycle to the exact Rippling payroll run      |
| Pay period start / end dates | Determines which elections apply to the run                     |
| Run status                   | Confirms the run is finalized before Toku settles               |
| Worker payroll records       | Reconciles the applied Toku line item against each worker's pay |

## Sync Behavior

* Upcoming payroll runs appear in the Toku dashboard as soon as they exist in Rippling.
* When a run is finalized, Toku reads the worker payroll records, reconciles the Toku line item on each participating worker's pay, and releases the corresponding stablecoin payments.
* Runs outside your regular pay schedule are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payroll runs in Rippling — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/rippling/deduction">
    How the Toku line item is reflected on the pay run
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/rippling/authentication">
    OAuth 2.0 scopes and token handling
  </Card>
</CardGroup>


# UKG Integration
Source: https://docs.toku.com/integrations/ukg

Run compliant stablecoin payroll alongside UKG with the Toku deduction

Toku integrates with **UKG** through UKG's web services APIs, using a dedicated service account under your control. UKG remains your payroll system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Link UKG to Toku with a dedicated, least-privilege service account.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your employee roster and upcoming payrolls from UKG automatically.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is posted to the pay run in UKG and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## The Toku Deduction

Stablecoin payments appear in UKG as one dedicated deduction on the employee's pay statement. Toku calculates the amount for each employee every pay period based on their election and posts it to upcoming payrolls through UKG's payroll integration APIs — no manual data entry, and no changes to your gross pay, taxes, or existing deduction codes.

The deduction is configured once during implementation. Toku's team provides the exact UKG configuration as part of onboarding.

## What You'll Need

* Admin access to your UKG tenant
* Ability to create a service account and a deduction plan
* Admin access to your Toku account

<Note>
  UKG can be used for payroll sync alongside a separate HCM (such as Workday, BambooHR, or Oracle) as your source of truth for employee data — or as the source of truth itself. You choose during setup.
</Note>

## Setup Overview

<Steps>
  <Step title="Create a service account">
    Your UKG administrator creates a dedicated service account for Toku with least-privilege web service permissions. Toku's implementation team provides the exact permission list.
  </Step>

  <Step title="Add the Toku deduction">
    Set up the dedicated Toku deduction plan in UKG and add it to the appropriate deduction groups. Toku provides the configuration during onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → UKG**, enter your tenant details and service account credentials, and connect.
  </Step>

  <Step title="Verify the sync">
    Toku validates the connection and begins pulling upcoming payrolls automatically.
  </Step>
</Steps>

<Note>
  Detailed, step-by-step configuration guides (with screenshots) are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs upcoming payrolls from UKG on a rolling basis.
2. Toku calculates each employee's stablecoin amount and posts the Toku deduction to the pay run.
3. You run payroll in UKG exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Employee and payroll data** syncs from UKG to Toku on a read-only basis.
* **Deduction data** is the only information Toku writes back to UKG.
* Access is scoped to a dedicated service account under your control, and all credentials are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against UKG's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/ukg/authentication">
    How Toku authenticates with UKG
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/ukg/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/ukg/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/ukg/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="ADP" icon="building" href="/integrations/adp">
    ADP Workforce Now payroll integration
  </Card>

  <Card title="Workday" icon="building" href="/integrations/workday">
    HCM and payroll integration
  </Card>
</CardGroup>


# UKG Pro API Authentication
Source: https://docs.toku.com/integrations/ukg/authentication

How Toku authenticates with UKG Pro web services using a dedicated service account and API keys

Toku connects to UKG Pro using a [dedicated Service Account](https://developer.ukg.com/hcm/docs/web-service-account) that your UKG administrator creates and controls. Access is scoped by the web-service roles you grant the account — you can disable it at any time to cut off access instantly.

## Service Account Setup

<Steps>
  <Step title="Create the service account">
    Your UKG admin creates a Service Account for Toku under **Menu → System Configuration → Security → Service Account Administration**, granting only the web-service roles Toku needs.
  </Step>

  <Step title="Collect the API keys">
    The same page shows your tenant's **Customer API key** and the service account's **User API key**. Both are entered into Toku along with the account credentials.
  </Step>

  <Step title="Connect from Toku">
    In **Settings → Payroll Integrations → UKG**, enter your tenant base URL, service account credentials, and API keys. Toku validates the connection with a read-only test call.
  </Step>
</Steps>

## REST Requests

UKG Pro's REST Core APIs use HTTP Basic authentication with the service account credentials, plus the `US-Customer-Api-Key` header carrying your tenant's Customer API key:

```bash theme={null}
curl "https://<hostname>.ultipro.com/personnel/v1/person-details" \
  -H "Authorization: Basic <base64(username:password)>" \
  -H "US-Customer-Api-Key: <customer_api_key>"
```

Your tenant base URL (e.g. `https://<hostname>.ultipro.com`) is unique to your environment — find it in UKG Pro under **System Configuration → Security → Web Services**.

## SOAP Login Service

Some payroll integration services are SOAP-based. For these, Toku first calls UKG's [Login Service](https://developer.ukg.com/hcm/docs/login-service) at `https://<hostname>/services/LoginService` with four headers — `UserName`, `Password`, `UserAccessKey` (the User API key), and `ClientAccessKey` (the Customer API key) — and receives a login token used on subsequent SOAP calls. Tokens are short-lived and rotated automatically.

## Permissions

UKG Pro scopes service accounts through per-domain web-service roles — for example, **View** on *Employee Person Details*, *Employee Compensation Details*, and *Personnel Integration*, and **Add** on *Payroll Integration*. Toku requests the minimum set needed for stablecoin payroll; the exact permission list is provided by Toku's implementation team during onboarding.

Any call outside the granted roles is rejected by UKG Pro. Disabling the service account or rotating its keys immediately revokes Toku's access.

## Environments

| Environment                                      | Base URL                                      |
| ------------------------------------------------ | --------------------------------------------- |
| Production                                       | `https://<hostname>.ultipro.com` (per-tenant) |
| Test tenant (used during implementation testing) | Provided by UKG for your account              |

<Note>
  See UKG's documentation on [service accounts](https://developer.ukg.com/hcm/docs/web-service-account) and the [Login Service](https://developer.ukg.com/hcm/docs/login-service) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="Employee Sync" icon="users" href="/integrations/ukg/employee-sync">
    How Toku reads your employee roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/ukg/payroll-sync">
    How Toku tracks pay groups and upcoming payrolls
  </Card>
</CardGroup>


# Applying the Toku Deduction in UKG Pro
Source: https://docs.toku.com/integrations/ukg/deduction

How Toku posts the stablecoin deduction to upcoming pay runs through UKG Pro's payroll integration services

Each pay period, Toku posts one dedicated deduction per participating employee to the upcoming pay run, through UKG Pro's Payroll Integration services. This is the only write Toku performs against your UKG Pro tenant.

## How It's Delivered

The deduction uses the customer-configured **Deduction/Benefit Plan** created during onboarding, applied as a flat amount at the employee level. UKG Pro exposes a pay-item import surface for delivering pay data into open runs — for example:

```bash theme={null}
POST https://<hostname>.ultipro.com/services/payroll/v1/import-pay-items/... \
  -H "x-correlation-id: <request_id>" \
  -H "us-client-id: <primary_company_code>" \
  -H "US-CUSTOMER-API-KEY: <customer_api_key>"
```

The exact deduction delivery path — API pay-item import versus UKG's **Pay Data Import** — is configured with UKG during implementation, since it depends on your tenant's payroll setup. Toku's implementation team handles this configuration with you; either way, the result is the same single Toku line item on the pay run.

## The Deduction Record

For each participating employee, the posted record carries:

| Field                       | Detail                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| Employee ID                 | The UKG Pro `employeeId` matched during [employee sync](/integrations/ukg/employee-sync) |
| Deduction/Benefit Plan code | The dedicated Toku plan configured during onboarding                                     |
| Amount                      | Flat amount — the employee's election determines the amount for each pay period          |
| Pay period                  | The upcoming pay run for the employee's pay group                                        |

The line item appears on the employee's pay statement under the Toku plan code, so payslips stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                                |
| ---------------- | --------------------------------------------------------------------- |
| One line item    | Exactly one Toku deduction per participating employee per run         |
| No gross changes | Gross pay, taxes, and every other pay item are untouched              |
| Bounded amount   | The deduction is validated against net pay before it is posted        |
| Reversible       | Removing an employee's election stops the deduction from the next run |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or existing deduction codes in UKG Pro — write access is limited to the Toku Deduction/Benefit Plan itself.
</Warning>

## Reconciliation

After the payroll is processed, Toku reads the finalized run via [`GET /payroll/v1/payroll-deductions-history`](https://developer.ukg.com/hcm/reference/payrolldeductionshistory_get), confirms each applied deduction against the employee's election, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/ukg">
    Back to the UKG integration overview
  </Card>

  <Card title="Employee Sync" icon="users" href="/integrations/ukg/employee-sync">
    How Toku reads your employee roster
  </Card>
</CardGroup>


# UKG Pro Employee Sync
Source: https://docs.toku.com/integrations/ukg/employee-sync

How Toku syncs your employee roster from UKG Pro

Toku keeps its employee roster in sync with UKG Pro so stablecoin elections always map to the right person and pay group. Sync is read-only and runs automatically after connection and on a rolling schedule.

## Endpoints

Toku reads employees through UKG Pro's Personnel REST APIs:

```bash theme={null}
curl "https://<hostname>.ultipro.com/personnel/v1/person-details?page=1&per_Page=100" \
  -H "Authorization: Basic <base64(username:password)>" \
  -H "US-Customer-Api-Key: <customer_api_key>"
```

A trimmed example response:

```json theme={null}
[
  {
    "employeeId": "AB1CD2000EFG",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "emailAddress": "ada@yourcompany.com",
    "dateOfBirth": null,
    "links": []
  }
]
```

See UKG's reference for the full schema: [Get person details](https://developer.ukg.com/hcm/reference/get_personnel-v1-person-details).

Alongside person details, Toku reads:

| Endpoint                                                     | Purpose                                                                                                                             |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `GET /personnel/v1/companies/{companyId}/employment-details` | Job title, employment status, and `payGroupCode` per employee                                                                       |
| `GET /personnel/v1/compensation-details`                     | Pay rate details, filterable by `companyId`, `employeeId`, and `payGroupCode`                                                       |
| `POST /personnel/v1/employee-ids`                            | Batch lookup of employee identifiers (a POST because identifiers are sensitive; returns `207 Multi-Status` with per-record results) |

## What Toku Reads

| Field                                   | Purpose                                                     |
| --------------------------------------- | ----------------------------------------------------------- |
| `employeeId`                            | Stable identifier used to match the employee across systems |
| `firstName`, `lastName`, `emailAddress` | Roster display and employee-portal invitations              |
| `payGroupCode`                          | Maps each employee to the correct pay group and pay run     |
| Employment status                       | Marks departed employees inactive in Toku                   |
| Compensation details                    | Validates election limits against compensation              |

## Pagination and Rate Limits

List endpoints are paginated with the `page` and `per_Page` query parameters; Toku walks pages until the roster is complete. UKG Pro enforces [gateway-level rate limits](https://developer.ukg.com/hcm/docs/api-rate-limiting) and returns `429` when they're breached — Toku backs off and retries automatically, so syncs never contend with your own integrations.

## Sync Behavior

* **New employees** appear in Toku automatically on the next sync after they're added in UKG Pro.
* **Updates** (name, email, pay group, compensation) flow through on the next sync.
* **Terminated employees** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Employee sync never writes to UKG Pro. Toku does not modify employee records, compensation, or employment status.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/ukg/payroll-sync">
    How Toku tracks pay groups and upcoming payrolls
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/ukg/deduction">
    How the deduction is posted each pay period
  </Card>
</CardGroup>


# UKG Pro Payroll Sync
Source: https://docs.toku.com/integrations/ukg/payroll-sync

How Toku tracks pay groups and upcoming payrolls in UKG Pro

Toku tracks your UKG Pro payroll calendar so the Toku deduction is always posted to the right pay run — and so on-chain delivery lines up with your pay date.

## How It Syncs

Toku pulls upcoming payrolls and pay groups from UKG Pro on a rolling cadence (roughly every 15 minutes) through UKG Pro's Payroll Integration web services, using the same service account as the rest of the integration. Each employee's `payGroupCode` (from [employee sync](/integrations/ukg/employee-sync)) determines which pay run their deduction belongs to.

For reconciliation, Toku also reads posted deductions through the payroll deductions history resource:

```bash theme={null}
curl "https://<hostname>.ultipro.com/payroll/v1/payroll-deductions-history?page=1&per_Page=100" \
  -H "Authorization: Basic <base64(username:password)>" \
  -H "US-Customer-Api-Key: <customer_api_key>"
```

A trimmed example response:

```json theme={null}
[
  {
    "employeeId": "AB1CD2000EFG",
    "payGroup": "BIWEEKLY",
    "periodControlDate": "2026-07-15",
    "deductionBenefitPlan": "TOKU",
    "employeeDeductionAmount": 250.00
  }
]
```

See UKG's reference for the full schema: [Payroll deductions history](https://developer.ukg.com/hcm/reference/payrolldeductionshistory_get). Reading it requires the **View** role on *Payroll Integration*.

## What Toku Reads

| Field                          | Purpose                                                     |
| ------------------------------ | ----------------------------------------------------------- |
| Pay group and pay period dates | Ties each Toku pay cycle to the exact UKG Pro pay run       |
| Period control / pay date      | Schedules on-chain stablecoin delivery                      |
| `deductionBenefitPlan`         | Filters history to the dedicated Toku deduction code        |
| `employeeDeductionAmount`      | Confirms the applied amount matches the employee's election |

## Sync Behavior

* Upcoming pay runs appear in the Toku dashboard shortly after they exist in UKG Pro.
* When a pay run is processed, Toku reconciles the applied deductions against the deductions history and releases the corresponding stablecoin payments.
* Off-cycle runs are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or submits payrolls in UKG Pro — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/ukg/deduction">
    How the deduction is posted each pay period
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/ukg/authentication">
    Service accounts, API keys, and permissions
  </Card>
</CardGroup>


# Workday Integration
Source: https://docs.toku.com/integrations/workday

Run compliant stablecoin payroll alongside Workday HCM and Workday Payroll with the Toku deduction

Toku integrates with **Workday** for both HCM and payroll, using Workday's standard integration tooling — an Integration System User (ISU), Reports-as-a-Service (RaaS), and Workday Web Services. Workday remains your system of record — Toku handles the digital-asset side.

## How It Works

<CardGroup>
  <Card title="1. Connect" icon="plug">
    Link Workday to Toku with a dedicated Integration System User and security group.
  </Card>

  <Card title="2. Sync" icon="rotate">
    Toku syncs your worker roster and payroll calendar from Workday via RaaS reports.
  </Card>

  <Card title="3. Elect" icon="hand-pointer">
    Employees choose what portion of their pay they'd like to receive in stablecoins.
  </Card>

  <Card title="4. Deduct & Deliver" icon="money-bill-transfer">
    Each pay period, a single Toku deduction is applied as payroll input in Workday and Toku delivers the corresponding stablecoin payment on-chain.
  </Card>
</CardGroup>

## Flexible Scope

The Workday integration supports two modes — use whichever fits your stack:

| Mode                        | What it does                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Employee sync only**      | Workday is your HCM; Toku syncs worker data while payroll runs elsewhere                                 |
| **Employee + payroll sync** | Workday also runs payroll; Toku additionally syncs pay runs and applies the Toku deduction automatically |

## The Toku Deduction

Stablecoin payments appear in Workday as one dedicated deduction on the employee's payslip. Toku calculates the amount for each employee every pay period based on their election and posts it as payroll input — either automatically through Workday Web Services or via a simple file import into your existing EIB, whichever your team prefers. Gross pay, taxes, and your existing earning and deduction codes are untouched.

The deduction is configured once during implementation. Toku's team provides the exact Workday configuration as part of onboarding.

## What You'll Need

* Admin access to your Workday tenant
* Security admin permissions to create an Integration System User and security group
* Admin access to your Toku account

## Setup Overview

<Steps>
  <Step title="Create an Integration System User">
    Your Workday administrator creates a dedicated ISU and security group for Toku with least-privilege domain permissions. Toku's implementation team provides the exact scope list.
  </Step>

  <Step title="Enable worker data sync">
    Create a custom report, enabled as a web service (RaaS), that exposes the worker fields Toku needs for matching and payments. Toku provides the report template during onboarding.
  </Step>

  <Step title="Add the Toku deduction">
    Set up the dedicated Toku deduction in Workday and add it to your payroll run categories. Toku provides the configuration during onboarding.
  </Step>

  <Step title="Connect from Toku">
    In the Toku dashboard, go to **Settings → Payroll Integrations → Add New Integration → Workday**, enter your tenant details and ISU credentials, preview the synced employees, and connect.
  </Step>
</Steps>

<Note>
  Detailed, step-by-step configuration guides (with screenshots) are provided to customers during implementation. [Contact the Toku team](https://www.toku.com/contact) to get started.
</Note>

## Each Pay Period

Once connected, the integration runs on autopilot:

1. Toku syncs worker changes from Workday — new hires are added, updates flow through, and terminated workers are marked inactive.
2. Toku calculates each employee's stablecoin amount and posts the Toku deduction to the pay run.
3. You run pay calculation in Workday exactly as you do today.
4. Toku delivers the stablecoin payments on-chain and provides full reporting and reconciliation.

## Data & Security

* **Worker data** syncs from Workday to Toku on a read-only basis via your RaaS report.
* **Deduction data** is the only information Toku writes back to Workday.
* Access is scoped to a dedicated ISU and security group under your control, and all credentials are encrypted at rest.

## API Reference

How the integration works at the API level, with calls you can validate against Workday's own documentation:

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integrations/workday/authentication">
    How Toku authenticates with Workday
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/workday/employee-sync">
    How Toku reads your roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/workday/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/workday/deduction">
    How the deduction is applied each pay period
  </Card>
</CardGroup>

## Related Integrations

<CardGroup>
  <Card title="ADP" icon="building" href="/integrations/adp">
    ADP Workforce Now payroll integration
  </Card>

  <Card title="UKG" icon="building" href="/integrations/ukg">
    UKG Pro payroll integration
  </Card>
</CardGroup>


# Workday API Authentication
Source: https://docs.toku.com/integrations/workday/authentication

How Toku authenticates with Workday using a dedicated Integration System User

Toku connects to Workday as a dedicated **Integration System User (ISU)** placed in its own Integration System Security Group. The group carries least-privilege domain security policies scoped to the integration — your Workday administrator creates both during setup and can revoke access at any time. Toku's implementation team provides the exact scope list during onboarding.

## Authentication Mechanisms

Workday exposes three API surfaces, each with its own documented authentication mechanism. Toku uses the same ISU across all three:

| API surface                      | Mechanism                  | Used for                              |
| -------------------------------- | -------------------------- | ------------------------------------- |
| RaaS custom reports              | HTTP Basic (`user@tenant`) | Worker and payroll report sync        |
| Workday Web Services (WWS, SOAP) | WS-Security UsernameToken  | Payroll results and payroll input     |
| Workday REST                     | OAuth 2.0                  | Token-based REST access where enabled |

### HTTP Basic (RaaS)

Report requests authenticate with basic auth, using the username form `user@tenant`:

```bash theme={null}
curl -u "ISU_TOKU@acme_tenant" \
  "https://<host>/ccx/service/customreport2/<tenant>/<report_owner>/<Report_Name>?format=json"
```

### WS-Security UsernameToken (WWS)

SOAP calls carry the ISU credentials in a WS-Security header:

```xml theme={null}
<wsse:Security soapenv:mustUnderstand="1">
  <wsse:UsernameToken>
    <wsse:Username>ISU_TOKU@acme_tenant</wsse:Username>
    <wsse:Password Type="...#PasswordText">********</wsse:Password>
  </wsse:UsernameToken>
</wsse:Security>
```

### OAuth 2.0 (Workday REST)

<Steps>
  <Step title="Register">
    Your Workday administrator runs the tenant task **Register API Client for Integration**, which yields a client ID and client secret.
  </Step>

  <Step title="Generate">
    A non-expiring refresh token is generated for the Toku ISU from the registered API client.
  </Step>

  <Step title="Exchange">
    Toku exchanges the refresh token for short-lived access tokens at the tenant's token endpoint — the connection stays live without re-authorization.
  </Step>
</Steps>

```bash theme={null}
# Token exchange (performed by Toku's backend)
curl -X POST "https://<host>/ccx/oauth2/<tenant>/token" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh_token>"
```

## Hosts

Workday hosts are tenant-specific — an implementation tenant might live at `wd2-impl-services1.workday.com`, while your production tenant lives elsewhere. Always copy the exact URL from your own tenant rather than reusing an example host.

<Note>
  After your administrator adjusts the ISU's security group, Workday requires running **Activate Pending Security Policy Changes** before the new access takes effect. See the [Workday Web Services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup>
  <Card title="Worker Sync" icon="users" href="/integrations/workday/employee-sync">
    How Toku reads your worker roster via RaaS
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/workday/payroll-sync">
    How Toku tracks pay runs and payroll results
  </Card>
</CardGroup>


# Applying the Toku Deduction in Workday
Source: https://docs.toku.com/integrations/workday/deduction

How Toku applies the stablecoin deduction as payroll input in Workday

Each pay period, Toku applies one dedicated deduction per participating worker as **payroll input** — Workday's mechanism for one-time earnings and deductions that supplement calculated payroll from external systems. The Toku deduction is a single pay component input per worker per period, and it is the only write Toku performs against your tenant.

## Delivery Paths

### Automated: Submit\_Payroll\_Input

The WWS `Payroll` service's **Submit\_Payroll\_Input** operation adds and updates payroll input data from external systems. Toku posts one input per worker before your pay calculation runs. A trimmed, illustrative request:

```xml theme={null}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wd="urn:com.workday/bsvc">
  <soapenv:Header>
    <wsse:Security><!-- WS-Security UsernameToken (see Authentication) --></wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <wd:Submit_Payroll_Input_Request wd:version="v44.0">
      <wd:Payroll_Input_Data>
        <wd:Worker_Reference>
          <wd:ID wd:type="Employee_ID">10023</wd:ID>
        </wd:Worker_Reference>
        <wd:Pay_Component_Reference>
          <wd:ID wd:type="Deduction_Code">TOKU_DEDUCTION</wd:ID>
        </wd:Pay_Component_Reference>
        <wd:Amount>250.00</wd:Amount>
        <!-- start/end dates and batch details trimmed -->
      </wd:Payroll_Input_Data>
    </wd:Submit_Payroll_Input_Request>
  </soapenv:Body>
</soapenv:Envelope>
```

### Manual: EIB Spreadsheet Import

If your team prefers to review before anything lands in Workday, use an inbound **Enterprise Interface Builder (EIB)** integration instead: a spreadsheet template bound to the same Submit\_Payroll\_Input web service. Toku exports the populated file each pay period, and your payroll team uploads it through the EIB.

See the [Workday Web Services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) and [Workday's EIB documentation](https://doc.workday.com/admin-guide/en-us/integrations/enterprise-interface-builder-eib-/dan1370796404498.html) to validate both paths.

<Note>
  If payroll runs **outside** Workday (Workday is HCM-only), the `Payroll_Interface` service's **Put\_External\_Payroll\_Input** operation is used instead — the same one-deduction model, delivered to your external payroll provider's interface.
</Note>

## How the Amount Is Set

* The worker's stablecoin election in Toku determines the amount for each pay period.
* Toku posts the input before each run, so one-off changes (paused elections, prorated periods) are handled automatically.
* The line item appears on the worker's payslip under the dedicated Toku pay component, so payslips stay self-explanatory.

## Guarantees

| Behavior         | Detail                                                                     |
| ---------------- | -------------------------------------------------------------------------- |
| One line item    | Exactly one Toku pay component input per participating worker per period   |
| No gross changes | Gross pay, taxes, and every other earning and deduction code are untouched |
| Bounded amount   | The deduction is validated against net pay before it is applied            |
| Reversible       | Removing a worker's election stops the input from the next period          |

<Warning>
  Toku never modifies compensation, tax withholding, benefits, or your existing pay components in Workday — write access is limited to the dedicated Toku deduction itself.
</Warning>

## Reconciliation

After the run completes, Toku reads the payroll results, confirms each applied deduction, and releases the matching on-chain stablecoin payments. Any mismatch blocks settlement and is surfaced in the Toku dashboard before funds move.

## Next

<CardGroup>
  <Card title="Integration Overview" icon="map" href="/integrations/workday">
    Back to the Workday integration overview
  </Card>

  <Card title="Worker Sync" icon="users" href="/integrations/workday/employee-sync">
    How Toku reads your worker roster via RaaS
  </Card>
</CardGroup>


# Workday Worker Sync
Source: https://docs.toku.com/integrations/workday/employee-sync

How Toku syncs your worker roster from Workday via a RaaS custom report

Toku keeps its worker roster in sync with Workday so stablecoin elections always map to the right person. Sync is read-only and runs through a **Reports-as-a-Service (RaaS)** custom report — a Workday report enabled as a web service — automatically after connection and on a rolling schedule.

## Endpoint

RaaS reports follow a standard URL format:

```text theme={null}
https://<host>/ccx/service/customreport2/<tenant>/<report_owner>/<Report_Name>?format=json
```

The `format` parameter also accepts `csv` and `xml`, and any report prompts pass as additional query parameters. Toku reads the worker demographics report your team creates during onboarding, authenticating with HTTP Basic as the ISU:

```bash theme={null}
curl -u "ISU_TOKU@acme_tenant" \
  "https://<host>/ccx/service/customreport2/acme_tenant/ISU_TOKU/Toku_Worker_Sync?format=json"
```

A trimmed example response — RaaS JSON always wraps rows in a `Report_Entry` array:

```json theme={null}
{
  "Report_Entry": [
    {
      "Employee_ID": "10023",
      "Worker": "Ada Lovelace",
      "Work_Email": "ada@yourcompany.com",
      "Country": "United States of America",
      "Currency": "USD",
      "Total_Base_Pay": "180000.00",
      "Worker_Status": "Active",
      "Pay_Group": "US Semi-Monthly"
    }
  ]
}
```

See the [Workday Web Services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) and this [RaaS reference](https://docs.workato.com/connectors/workday/workday_raas.html) to validate the URL format and response shape.

## What Toku Reads

| Field                  | Purpose                                                   |
| ---------------------- | --------------------------------------------------------- |
| `Employee_ID`          | Stable identifier used to match the worker across systems |
| `Worker`, `Work_Email` | Roster display and employee-portal invitations            |
| `Country`, `Currency`  | Determines payment rails and settlement currency          |
| `Total_Base_Pay`       | Validates election limits against compensation            |
| `Worker_Status`        | Marks departed workers inactive in Toku                   |
| `Pay_Group`            | Ties each worker to the right payroll calendar            |

## Sync Behavior

* **New workers** appear in Toku automatically once they show up in the report.
* **Updates** (name, email, compensation, pay group) flow through on the next sync.
* **Terminated workers** are marked inactive and stop receiving stablecoin payments.
* A manual sync can be triggered anytime from **Settings → Payroll Integrations** in Toku.

<Note>
  Worker sync never writes to Workday. The report is owned by your tenant — your team controls exactly which fields it exposes, and Toku only sees what the report returns.
</Note>

## Next

<CardGroup>
  <Card title="Payroll Sync" icon="calendar" href="/integrations/workday/payroll-sync">
    How Toku tracks pay runs and payroll results
  </Card>

  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/workday/deduction">
    How the deduction is applied as payroll input
  </Card>
</CardGroup>


# Workday Payroll Sync
Source: https://docs.toku.com/integrations/workday/payroll-sync

How Toku tracks pay runs and payroll results in Workday

Toku tracks your Workday payroll calendar so the Toku deduction is always applied to the right pay period — and so on-chain delivery lines up with your pay date. Payroll sync uses the **Workday Web Services (WWS)** `Payroll` service, a payroll RaaS report, or both.

## Workday Web Services

The SOAP `Payroll` service is described by a versioned WSDL on your tenant:

```text theme={null}
https://<host>/ccx/service/<tenant>/Payroll/v44.0?wsdl
```

Toku calls the **Get\_Payroll\_Results** operation, which returns payroll results filtered by worker, company, and date range. Requests authenticate with the WS-Security UsernameToken header described in [Authentication](/integrations/workday/authentication). The current WWS directory version is v46.1 — pin the version your tenant supports.

See the [Workday Web Services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) and its Payroll service page to validate the operations referenced here.

## Payroll RaaS Report

As an alternative (or supplement), Toku can read a payroll custom report enabled as a web service, using the same URL format as [worker sync](/integrations/workday/employee-sync). A trimmed example response:

```json theme={null}
{
  "Report_Entry": [
    {
      "Employee_ID": "10023",
      "Pay_Group": "US Semi-Monthly",
      "Period_Start_Date": "2026-07-01",
      "Period_End_Date": "2026-07-15",
      "Payment_Date": "2026-07-20",
      "Gross_Amount": "7500.00",
      "Net_Amount": "5480.25",
      "Payroll_Status": "Complete"
    }
  ]
}
```

## What Toku Reads

| Field                        | Purpose                                           |
| ---------------------------- | ------------------------------------------------- |
| `Pay_Group` / period dates   | Determines which elections apply to the run       |
| `Payment_Date`               | Schedules on-chain stablecoin delivery            |
| `Gross_Amount`, `Net_Amount` | Validates the deduction against the worker's pay  |
| `Payroll_Status`             | Confirms the run is finalized before Toku settles |

## Sync Behavior

* Upcoming pay periods appear in the Toku dashboard as soon as they exist in Workday.
* When a run's status flips to complete, Toku reconciles the applied deductions against the results and releases the corresponding stablecoin payments.
* Off-cycle runs are detected and skipped by default (configurable during onboarding).

<Note>
  Payroll sync is read-only. Toku never creates, calculates, or completes pay runs in Workday — your team keeps full control of running payroll.
</Note>

## Next

<CardGroup>
  <Card title="The Toku Deduction" icon="money-bill-transfer" href="/integrations/workday/deduction">
    How the deduction is applied as payroll input
  </Card>

  <Card title="Authentication" icon="lock" href="/integrations/workday/authentication">
    ISU credentials and the three auth mechanisms
  </Card>
</CardGroup>


# Enabling Stablecoin Payroll
Source: https://docs.toku.com/payroll/client/enabling-stablecoin-payroll

Set up stablecoin payroll for your organization

## Overview

Enable stablecoin payroll to offer employees the option to receive part or all of their compensation in stablecoins.

***

## Setup Process

<Steps>
  <Step title="Navigate to Payroll Settings">
    Go to **Settings** > **Payroll**
  </Step>

  <Step title="Enable Stablecoin Payroll">
    Toggle on **Stablecoin Payroll** feature
  </Step>

  <Step title="Configure stablecoins">
    Select which stablecoins to offer:

    * USDC
    * USDT
    * DAI
    * Others
  </Step>

  <Step title="Set network options">
    Choose supported blockchain networks:

    * Ethereum
    * Polygon
    * Arbitrum
    * Optimism
  </Step>

  <Step title="Configure limits">
    Set employee options:

    * Maximum percentage allowed in stablecoins
    * Minimum dollar threshold
    * Opt-in requirements
  </Step>

  <Step title="Connect funding source">
    Link your treasury or custody account for funding
  </Step>
</Steps>

***

## Configuration Options

### Stablecoin Selection

Choose which stablecoins employees can receive:

| Option               | Recommendation                       |
| -------------------- | ------------------------------------ |
| **USDC only**        | Simplest, widest support             |
| **USDC + USDT**      | More choice, still straightforward   |
| **Multiple options** | Maximum flexibility, more complexity |

### Employee Limits

Configure how much employees can receive in stablecoins:

| Setting            | Description                                           |
| ------------------ | ----------------------------------------------------- |
| **Maximum %**      | Highest percentage of pay in stablecoins (e.g., 100%) |
| **Minimum %**      | Lowest percentage if opted in (e.g., 10%)             |
| **Minimum amount** | Dollar floor for stablecoin payments                  |

***

## Funding Setup

### Treasury Connection

Connect your funding source:

1. Link your custody provider (Fireblocks, Coinbase, etc.)
2. Configure the funding wallet
3. Set up auto-funding rules

### Funding Requirements

Ensure you have sufficient stablecoins to cover:

* Expected payroll amounts
* Buffer for rate fluctuations
* Multiple payroll cycles

***

## Employee Enrollment

### Automatic Opt-In

All eligible employees can choose stablecoin payments.

### Invitation-Based

Invite specific groups of employees:

* By department
* By location
* By employee level

### Manual Approval

Require admin approval for each enrollment.

***

## Compliance Settings

Configure compliance requirements:

| Setting                     | Options                                     |
| --------------------------- | ------------------------------------------- |
| **KYC Requirement**         | Required / Optional for stablecoin payments |
| **Wallet Verification**     | Test transaction / Signature / None         |
| **Geographic Restrictions** | Exclude certain jurisdictions               |

***

## Integration

### HRIS Connection

Connect your HR system for employee data:

* ADP
* Workday
* UKG
* BambooHR

<Card title="HRIS Integration" icon="plug" href="/payroll/client/payroll-integration-setup">
  Set up your HR integration
</Card>

### Payroll Provider

If using an external payroll provider, configure the integration to sync payroll data.

***

<Tip>
  **Payroll Client Guide** — Step 1 of 5. [Next: Supported Stablecoins](/payroll/client/supported-stablecoins)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Supported Stablecoins" icon="coins" href="/payroll/client/supported-stablecoins">
    Learn about stablecoin options
  </Card>

  <Card title="Run Payroll" icon="play" href="/payroll/client/running-payroll">
    Process your first payroll
  </Card>
</CardGroup>


# Payroll Integration Setup
Source: https://docs.toku.com/payroll/client/payroll-integration-setup

Connect your HR and payroll systems

## Overview

Connect Toku to your existing HR and payroll systems to sync employee data and payroll information automatically.

***

## Supported Integrations

<CardGroup>
  <Card title="ADP" icon="building" href="/integrations/adp">
    Workforce Now, RUN, and other ADP products
  </Card>

  <Card title="Workday" icon="building" href="/integrations/workday">
    HR and payroll integration
  </Card>

  <Card title="UKG" icon="building" href="/integrations/ukg">
    UKG Pro, Ready, and Dimensions
  </Card>

  <Card title="Deel" icon="building" href="/integrations/deel">
    Deel Global Payroll
  </Card>

  <Card title="Rippling" icon="building" href="/integrations/rippling">
    HR and payroll integration
  </Card>

  <Card title="Papaya Global" icon="building" href="/integrations/papaya-global">
    Global payroll and payments
  </Card>

  <Card title="Paychex" icon="building" href="/integrations/paychex">
    Paychex Flex payroll
  </Card>

  <Card title="Gusto" icon="building" href="/integrations/gusto">
    Payroll and HR
  </Card>

  <Card title="BambooHR" icon="building">
    Core HR and payroll
  </Card>
</CardGroup>

***

## Integration Setup

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Settings** > **Integrations**
  </Step>

  <Step title="Select your provider">
    Choose your HR/payroll system from the list
  </Step>

  <Step title="Authenticate">
    Follow the authentication flow:

    * Enter API credentials
    * Or use OAuth to connect
  </Step>

  <Step title="Configure sync settings">
    Set up what data to sync:

    * Employee roster
    * Pay schedules
    * Salary information
  </Step>

  <Step title="Map fields">
    Map your system's fields to Toku fields
  </Step>

  <Step title="Test connection">
    Verify the integration is working correctly
  </Step>
</Steps>

***

## Data Sync

### What Syncs

| Data            | Direction   | Frequency          |
| --------------- | ----------- | ------------------ |
| Employee roster | HRIS → Toku | Daily or on-demand |
| Pay schedules   | HRIS → Toku | As updated         |
| Salary changes  | HRIS → Toku | As updated         |
| Payment records | Toku → HRIS | After each payroll |

### Sync Settings

Configure how often data syncs:

* **Real-time** — Changes sync immediately
* **Daily** — Sync once per day
* **Manual** — Sync on-demand only

***

## ADP Integration

### Setup Requirements

* ADP API access (request from your ADP rep)
* API credentials or OAuth
* Company code

### Available Features

* Employee data sync
* Pay schedule import
* Payroll data export

***

## Workday Integration

### Setup Requirements

* Workday tenant access
* Integration system user
* RAAS report configuration

### Available Features

* Employee and position data
* Compensation information
* Payroll integration

***

## UKG Integration

### Setup Requirements

* UKG API credentials
* Company configuration
* Admin access

### Available Features

* Employee roster sync
* Time and attendance data
* Payroll integration

***

## BambooHR Integration

### Setup Requirements

* BambooHR API key
* Admin access

### Available Features

* Employee directory sync
* Compensation data
* Custom field mapping

***

## Manual Data Entry

If you don't use a supported HRIS:

1. Navigate to **Payroll** > **Employees**
2. Add employees manually or import via CSV
3. Enter compensation details
4. Set up stablecoin preferences

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration won't connect">
    Verify your API credentials and permissions. Contact your HRIS provider if needed.
  </Accordion>

  <Accordion title="Data isn't syncing">
    Check sync settings and ensure the integration is enabled. Try a manual sync.
  </Accordion>

  <Accordion title="Missing employees">
    Verify employee status in your HRIS. Inactive or terminated employees may not sync.
  </Accordion>
</AccordionGroup>

***

<Tip>
  **Payroll Client Guide** — Step 3 of 5. [Previous: Supported Stablecoins](/payroll/client/supported-stablecoins) | [Next: Running Payroll](/payroll/client/running-payroll)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Run Payroll" icon="play" href="/payroll/client/running-payroll">
    Process your first payroll
  </Card>

  <Card title="Reporting" icon="chart-bar" href="/payroll/client/reporting">
    Generate payroll reports
  </Card>
</CardGroup>


# Payroll Reporting
Source: https://docs.toku.com/payroll/client/reporting

Generate reports for stablecoin payroll

## Overview

Toku provides comprehensive reporting for stablecoin payroll, including payment history, tax summaries, and compliance documentation.

***

## Available Reports

<CardGroup>
  <Card title="Payroll Summary" icon="file-lines">
    Overview of each payroll run
  </Card>

  <Card title="Employee Payments" icon="users">
    Per-employee payment details
  </Card>

  <Card title="Tax Withholding" icon="file-invoice-dollar">
    Withholding summary by jurisdiction
  </Card>

  <Card title="Stablecoin Transactions" icon="coins">
    Blockchain transaction records
  </Card>
</CardGroup>

***

## Generating Reports

<Steps>
  <Step title="Navigate to Reports">
    Click **Reports** in the sidebar
  </Step>

  <Step title="Select report type">
    Choose the report you need
  </Step>

  <Step title="Set parameters">
    Configure date range and filters
  </Step>

  <Step title="Generate">
    Click **Generate Report**
  </Step>

  <Step title="Export">
    Download as CSV, PDF, or Excel
  </Step>
</Steps>

***

## Report Details

### Payroll Summary Report

High-level view of payroll runs:

* Pay period and date
* Total gross, withholding, and net
* Stablecoin vs. fiat breakdown
* Number of employees paid

### Employee Payment Report

Detailed per-employee:

* Gross pay
* All withholdings and deductions
* Net pay amount
* Stablecoin amount and wallet address
* Transaction hash (for stablecoin payments)

### Tax Withholding Report

For compliance and remittance:

* Withholding by jurisdiction (federal, state, local)
* Employee-level detail
* Totals for remittance

### Transaction Report

Blockchain-specific:

* Transaction hashes
* Wallet addresses
* Amounts in stablecoin and USD
* Transaction status and confirmations

***

## Scheduled Reports

Set up automatic report delivery:

1. Go to **Reports** > **Scheduled**
2. Select report type
3. Configure frequency
4. Add recipient emails
5. Save schedule

Reports are delivered via email on your schedule.

***

## Accounting Integration

Export data for your accounting system:

### QuickBooks

Export payroll journal entries compatible with QuickBooks.

### NetSuite

Export in NetSuite-compatible format.

### General Ledger

Generate standard GL entries for any accounting system.

***

## Compliance Documentation

Generate documentation for audits and compliance:

| Document                | Purpose                             |
| ----------------------- | ----------------------------------- |
| **Payment Proof**       | Blockchain verification of payments |
| **Tax Filing Support**  | Documentation for tax filings       |
| **Employee Statements** | Individual payment records          |
| **Annual Summary**      | Year-end compilation                |

***

## Data Retention

Toku retains all payroll records:

* Real-time access to current year data
* Archive access to historical data
* Meets standard data retention requirements

***

<Tip>
  **Payroll Client Guide** — Step 5 of 5. [Previous: Running Payroll](/payroll/client/running-payroll)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Payroll FAQ" icon="circle-question" href="/payroll/faq">
    Common questions
  </Card>

  <Card title="Contact Support" icon="headset" href="/getting-started/support">
    Get help with reporting
  </Card>
</CardGroup>


# Running Payroll
Source: https://docs.toku.com/payroll/client/running-payroll

Process stablecoin payroll for your employees

## Overview

Process payroll to pay employees their stablecoin compensation. Toku handles the conversion, tax withholding, and distribution automatically.

***

## Payroll Process

<Steps>
  <Step title="Review payroll data">
    Check that employee data is up to date and stablecoin elections are configured.
  </Step>

  <Step title="Create payroll run">
    Navigate to **Payroll** > **Run Payroll** and create a new payroll.
  </Step>

  <Step title="Set pay period">
    Select the pay period and pay date.
  </Step>

  <Step title="Review calculations">
    Verify gross pay, withholdings, and net amounts.
  </Step>

  <Step title="Approve payroll">
    Review the summary and approve for processing.
  </Step>

  <Step title="Process payments">
    Payments are sent to employee wallets.
  </Step>
</Steps>

***

## Creating a Payroll Run

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Navigate to Payroll">
        Click **Payroll** in the sidebar.
      </Step>

      <Step title="Click Run Payroll">
        Select **Run Payroll** to start a new run.
      </Step>

      <Step title="Select pay period">
        Choose:

        * Pay period start and end dates
        * Pay date
        * Payroll type (regular, bonus, off-cycle)
      </Step>

      <Step title="Review employees">
        See all employees included in this payroll.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    Use the [Create On-Cycle Payroll](/api/payroll/create-on-cycle) or [Create Off-Cycle Payroll](/api/payroll/create-off-cycle) endpoint:

    ```bash theme={null}
    curl -X POST "https://api.toku.com/api/payroll/createOnCyclePayroll" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "orgID": 100,
        "startDate": "2025-02-01",
        "endDate": "2025-02-28",
        "payDate": "2025-02-28"
      }'
    ```

    After creation, [finalize the payroll](/api/payroll/finalize) to approve it for processing.
  </Tab>
</Tabs>

***

## Payroll Calculations

### Gross to Net

For each employee, Toku calculates:

| Component             | Description                       |
| --------------------- | --------------------------------- |
| **Gross Pay**         | Total compensation for the period |
| **Tax Withholding**   | Federal, state, and local taxes   |
| **Deductions**        | Benefits, 401k, etc.              |
| **Net Pay**           | Amount to be distributed          |
| **Stablecoin Amount** | Net pay × stablecoin percentage   |
| **Fiat Amount**       | Net pay × fiat percentage         |

### Stablecoin Conversion

1. Net stablecoin amount determined
2. Exchange rate locked at processing time
3. Exact stablecoin amount calculated
4. Amount sent to employee wallet

***

## Review and Approval

### Payroll Summary

Before approving, review:

* Total gross payroll
* Total withholdings
* Total net payroll
* Stablecoin vs. fiat breakdown
* Per-employee details

### Approval Workflow

Depending on your settings:

* Single approver
* Multiple approvers
* Automatic approval below threshold

***

## Payment Processing

### Stablecoin Payments

* Sent immediately upon approval
* Arrive in employee wallets same day
* Transaction hashes provided

### Traditional Payments

* Processed through your bank or payroll provider
* Standard ACH timing applies

***

## Payroll Types

### Regular Payroll

Standard scheduled payroll (weekly, bi-weekly, monthly).

### Bonus Payroll

One-time bonus payments outside regular schedule.

### Off-Cycle Payroll

Corrections, termination pay, or special payments.

***

## Payroll Status

```mermaid theme={null}
stateDiagram-v2
    [*] --> Draft
    Draft --> PendingApproval : Submit
    PendingApproval --> Approved : Approve
    PendingApproval --> Draft : Reject
    Approved --> Processing : Begin processing
    Processing --> Completed : All payments succeed
    Processing --> PartiallyCompleted : Some payments fail
    Draft --> Cancelled : Cancel
    PendingApproval --> Cancelled : Cancel
```

| Status                  | Description                        |
| ----------------------- | ---------------------------------- |
| **Draft**               | Payroll created, not yet submitted |
| **Pending Approval**    | Awaiting approver action           |
| **Approved**            | Approved, payments processing      |
| **Processing**          | Payments being sent                |
| **Completed**           | All payments successful            |
| **Partially Completed** | Some payments failed               |

***

## After Payroll

Once payroll completes:

* Employees receive payment notifications
* Payslips are generated
* Transaction records are stored
* Reports are updated

***

<Tip>
  **Payroll Client Guide** — Step 4 of 5. [Previous: Payroll Integration Setup](/payroll/client/payroll-integration-setup) | [Next: Payroll Reporting](/payroll/client/reporting)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Reporting" icon="chart-bar" href="/payroll/client/reporting">
    View payroll reports
  </Card>

  <Card title="Payroll FAQ" icon="circle-question" href="/payroll/faq">
    Common questions
  </Card>
</CardGroup>


# Supported Stablecoins
Source: https://docs.toku.com/payroll/client/supported-stablecoins

Stablecoins and networks available for payroll

## Overview

Toku supports multiple stablecoins across various blockchain networks, giving you flexibility in how you pay employees.

***

## Available Stablecoins

### USDC (USD Coin)

The most widely supported stablecoin, issued by Circle.

| Attribute      | Details                                       |
| -------------- | --------------------------------------------- |
| **Issuer**     | Circle                                        |
| **Peg**        | 1:1 with USD                                  |
| **Networks**   | Ethereum, Polygon, Arbitrum, Optimism, Solana |
| **Compliance** | Regulated, audited reserves                   |

**Recommended for:** Most organizations due to wide support and regulatory clarity.

***

### USDT (Tether)

The largest stablecoin by market cap.

| Attribute      | Details                                     |
| -------------- | ------------------------------------------- |
| **Issuer**     | Tether                                      |
| **Peg**        | 1:1 with USD                                |
| **Networks**   | Ethereum, Polygon, Tron                     |
| **Compliance** | Widely used, some regulatory considerations |

**Recommended for:** Organizations with employees who prefer Tether or specific network support.

***

### DAI

A decentralized, crypto-collateralized stablecoin.

| Attribute      | Details                         |
| -------------- | ------------------------------- |
| **Issuer**     | MakerDAO                        |
| **Peg**        | 1:1 with USD                    |
| **Networks**   | Ethereum, Polygon               |
| **Compliance** | Decentralized, no single issuer |

**Recommended for:** Organizations wanting decentralized options.

***

## Network Comparison

| Network      | Speed         | Cost          | Best For           |
| ------------ | ------------- | ------------- | ------------------ |
| **Ethereum** | \~12 seconds  | Higher fees   | Maximum security   |
| **Polygon**  | \~2 seconds   | Very low fees | Cost efficiency    |
| **Arbitrum** | \~2 seconds   | Low fees      | Ethereum ecosystem |
| **Optimism** | \~2 seconds   | Low fees      | Ethereum ecosystem |
| **Solana**   | \~0.4 seconds | Very low fees | Speed priority     |

***

## Choosing a Stablecoin

### Considerations

| Factor                      | Recommendation                                    |
| --------------------------- | ------------------------------------------------- |
| **Employee preference**     | USDC is most familiar to newcomers                |
| **Geographic availability** | USDC has widest exchange support                  |
| **Cost**                    | Layer 2 networks (Polygon, Arbitrum) are cheapest |
| **Speed**                   | All options offer fast settlement                 |

### Common Configurations

**Simple (recommended for most):**

* USDC on Polygon
* Single option for employees

**Flexible:**

* USDC on Ethereum, Polygon, and Arbitrum
* Employee chooses network

**Maximum choice:**

* USDC + USDT
* Multiple networks
* Employee selects preferred combination

***

## Exchange Rate Handling

### Rate Source

Toku uses real-time rates from major exchanges to convert fiat to stablecoins.

### Rate Locking

* Rate is locked at time of payroll processing
* Employees receive the exact amount specified
* No exposure to rate fluctuation after locking

***

## Custody and Security

All stablecoins are held in institutional custody:

* Fireblocks
* Anchorage
* Coinbase Prime

Funds are secured until payroll is processed and distributed.

***

<Tip>
  **Payroll Client Guide** — Step 2 of 5. [Previous: Enabling Stablecoin Payroll](/payroll/client/enabling-stablecoin-payroll) | [Next: Payroll Integration Setup](/payroll/client/payroll-integration-setup)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Integration Setup" icon="plug" href="/payroll/client/payroll-integration-setup">
    Connect your payroll system
  </Card>

  <Card title="Run Payroll" icon="play" href="/payroll/client/running-payroll">
    Process stablecoin payroll
  </Card>
</CardGroup>


# Payroll FAQ
Source: https://docs.toku.com/payroll/faq

Frequently asked questions about Stablecoin Payroll

## For Employees

<AccordionGroup>
  <Accordion title="What is stablecoin payroll?">
    Stablecoin payroll allows you to receive part or all of your pay in stablecoins (like USDC) instead of traditional bank deposits. Stablecoins are digital currencies pegged to the US dollar.
  </Accordion>

  <Accordion title="Do I have to use stablecoin payments?">
    No, it's optional. You can continue receiving 100% of your pay via traditional bank deposit if you prefer.
  </Accordion>

  <Accordion title="What stablecoins can I receive?">
    Typically USDC, though your employer may offer other options like USDT or DAI. Check your payroll settings to see what's available.
  </Accordion>

  <Accordion title="Is it safe?">
    Stablecoins like USDC are designed to maintain a 1:1 value with USD. However, they are digital assets with some risk. The value is stable but not guaranteed by the government like bank deposits.
  </Accordion>

  <Accordion title="What wallet should I use?">
    We recommend self-custody wallets like MetaMask, Coinbase Wallet, or Rainbow. Avoid using exchange deposit addresses as your primary wallet.
  </Accordion>

  <Accordion title="How do I set up a wallet?">
    Download a wallet app, create a new wallet, securely store your recovery phrase, and copy your wallet address into Toku.
  </Accordion>

  <Accordion title="Can I change my split percentage?">
    Yes, you can change how much goes to your bank vs. your wallet at any time. Changes apply to the next pay cycle.
  </Accordion>

  <Accordion title="Are stablecoin payments taxed?">
    Yes, stablecoin compensation is taxable income just like regular pay. Your employer withholds taxes the same way regardless of payment method.
  </Accordion>

  <Accordion title="What if I sent it to the wrong address?">
    Crypto sent to the wrong address typically cannot be recovered. Always double-check your wallet address before saving it.
  </Accordion>

  <Accordion title="I don't see my stablecoins in my wallet">
    Make sure you're on the correct network and that you've added the stablecoin token to your wallet. Check the transaction hash on a block explorer to confirm the transfer.
  </Accordion>
</AccordionGroup>

***

## For Employers

<AccordionGroup>
  <Accordion title="How do I enable stablecoin payroll?">
    Go to **Settings** > **Payroll**, enable stablecoin payroll, configure the stablecoins and networks you want to offer, and set employee options.
  </Accordion>

  <Accordion title="What stablecoins should we offer?">
    USDC on Polygon is the most common choice — it's widely supported, compliant, and has low transaction fees. You can offer additional options based on employee preferences.
  </Accordion>

  <Accordion title="How do we fund stablecoin payments?">
    Connect your custody provider (Fireblocks, Coinbase, etc.) and ensure you have sufficient stablecoin balance to cover payroll.
  </Accordion>

  <Accordion title="How is tax withholding handled?">
    Toku calculates and applies tax withholding the same way for stablecoin payments as traditional payments. Net pay (after withholding) is what gets converted to stablecoins.
  </Accordion>

  <Accordion title="Can we limit who can opt in?">
    Yes, you can configure eligibility by department, location, or other criteria. You can also require approval for each enrollment.
  </Accordion>

  <Accordion title="What reporting is available?">
    Toku provides payroll summaries, employee payment reports, tax withholding reports, and stablecoin transaction records.
  </Accordion>

  <Accordion title="How do we handle employees in different jurisdictions?">
    Toku handles tax withholding according to each employee's jurisdiction. Some locations may have restrictions on stablecoin payments.
  </Accordion>

  <Accordion title="What if an employee enters the wrong wallet address?">
    Employees are responsible for providing correct wallet addresses. We recommend requiring wallet verification before the first payment.
  </Accordion>
</AccordionGroup>

***

## General

<AccordionGroup>
  <Accordion title="What is USDC?">
    USDC (USD Coin) is a stablecoin issued by Circle, designed to maintain a 1:1 value with the US dollar. It's one of the most widely used and regulated stablecoins.
  </Accordion>

  <Accordion title="What networks are supported?">
    Common networks include Ethereum, Polygon, Arbitrum, and Optimism. The specific options depend on your employer's configuration.
  </Accordion>

  <Accordion title="What are gas fees?">
    Gas fees are transaction costs on blockchain networks. Toku typically covers these fees for payroll payments, but employees may incur fees when moving or using their stablecoins.
  </Accordion>

  <Accordion title="How do I contact support?">
    Email [support@toku.com](mailto:support@toku.com) or visit the Support page for help.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

<Card title="Contact Support" icon="headset" href="/getting-started/support">
  Get in touch with our team
</Card>


# Stablecoin Payroll
Source: https://docs.toku.com/payroll/overview

Pay employees in stablecoins with built-in compliance

## What is Stablecoin Payroll?

Stablecoin Payroll is Toku's solution for paying employees in digital currencies while maintaining full compliance. It helps organizations:

* Offer stablecoin compensation as an employee benefit
* Process payroll in USDC, USDT, or other stablecoins
* Handle tax withholding and reporting automatically
* Integrate with existing HR and payroll systems
* Provide employees with flexible payout options

***

## Who Uses Stablecoin Payroll?

### Clients (Administrators)

Organization admins enable stablecoin payroll, configure settings, and process payments.

<Card title="Client Guides" icon="user-gear" href="/payroll/client/enabling-stablecoin-payroll">
  Set up stablecoin payroll
</Card>

### Employees

Employees opt into stablecoin payments and receive funds in their crypto wallets.

<Card title="Employee Guides" icon="user" href="/payroll/user/choosing-payout-method">
  Learn about receiving payments
</Card>

***

## How It Works

```mermaid theme={null}
flowchart LR
    A[Enable Payroll] --> B[Employee Opts In]
    B --> C[Run Payroll]
    C --> D[Tax Withheld]
    D --> E[Stablecoin Sent]
    E --> F[Employee Receives USDC]
```

***

## Key Features

<CardGroup>
  <Card title="Multiple Stablecoins" icon="coins">
    Support for USDC, USDT, and other major stablecoins
  </Card>

  <Card title="Tax Compliance" icon="file-invoice-dollar">
    Automatic tax withholding and reporting
  </Card>

  <Card title="HRIS Integration" icon="plug">
    Connect with your existing HR and payroll systems
  </Card>

  <Card title="Employee Choice" icon="hand-pointer">
    Let employees choose their payout mix
  </Card>

  <Card title="Multi-Network" icon="network-wired">
    Deploy on Ethereum, Polygon, and other networks
  </Card>

  <Card title="Instant Payments" icon="bolt">
    Same-day settlement for crypto payments
  </Card>
</CardGroup>

***

## Example: Paying Sarah in USDC

Sarah is a software engineer at Acme Corp. She's elected to receive 40% of her net pay in USDC on Polygon.

**1. Acme runs their bi-weekly payroll.** Toku calculates Sarah's gross pay of $7,500, withholds $2,100 in taxes, and determines her net pay of \$5,400.

**2. Toku splits the payout.** Based on Sarah's 40% election:

* **\$3,240** is deposited to her bank account via ACH
* **\$2,160** is converted to USDC

**3. Stablecoin is sent on-chain.** Toku locks the exchange rate at processing time, converts \$2,160 → 2,160.00 USDC, and sends it to Sarah's wallet on Polygon.

```json theme={null}
{
  "employee": "Sarah Chen",
  "grossPay": 7500.00,
  "taxWithholding": 2100.00,
  "netPay": 5400.00,
  "fiatAmount": 3240.00,
  "stablecoinAmount": 2160.00,
  "stablecoin": "USDC",
  "network": "Polygon",
  "walletAddress": "0x1a2B...9cDE",
  "status": "Completed",
  "txHash": "0xabc123...def456"
}
```

**4. Sarah sees the deposit** in her wallet within minutes. Her payslip shows the full breakdown: gross pay, taxes, fiat deposit, and stablecoin transfer with the on-chain transaction hash.

***

## Supported Stablecoins

| Stablecoin | Networks                              |
| ---------- | ------------------------------------- |
| **USDC**   | Ethereum, Polygon, Arbitrum, Optimism |
| **USDT**   | Ethereum, Polygon, Tron               |
| **DAI**    | Ethereum, Polygon                     |

***

## Getting Started

<CardGroup>
  <Card title="Enable Stablecoin Payroll" icon="toggle-on" href="/payroll/client/enabling-stablecoin-payroll">
    Set up for your organization
  </Card>

  <Card title="For Employees" icon="user" href="/payroll/user/choosing-payout-method">
    Choose your payout method
  </Card>
</CardGroup>

***

## Ready to use Toku?

<div>
  <div>
    <h3>Start offering stablecoin payroll</h3>

    <p>
      Give employees flexible payout options while keeping payroll compliance in one place.
    </p>
  </div>

  <a href="https://www.toku.com/get-started">
    Sign up for Toku
  </a>
</div>


# Choosing Your Payout Method
Source: https://docs.toku.com/payroll/user/choosing-payout-method

Select how you want to receive your pay

## Overview

If your employer offers stablecoin payroll, you can choose to receive part or all of your pay in stablecoins instead of traditional bank deposits.

***

## Your Options

### Traditional (Bank Deposit)

Receive 100% of your pay via direct deposit to your bank account.

### Stablecoin

Receive part or all of your pay in stablecoins (like USDC) to your crypto wallet.

### Hybrid

Split your pay between bank deposit and stablecoin — for example, 70% to your bank and 30% in USDC.

***

## Setting Your Preference

<Steps>
  <Step title="Log in to Toku">
    Access your employee portal
  </Step>

  <Step title="Navigate to Payroll Settings">
    Click **Settings** > **Payroll**
  </Step>

  <Step title="Choose your method">
    Select your preferred payout:

    * 100% traditional
    * 100% stablecoin
    * Custom split
  </Step>

  <Step title="Set up your wallet">
    If choosing stablecoin, add your wallet address
  </Step>

  <Step title="Confirm">
    Save your preferences
  </Step>
</Steps>

***

## Stablecoin Options

Depending on your employer's configuration, you may be able to choose:

### Which Stablecoin

* USDC (most common)
* USDT
* DAI

### Which Network

* Ethereum (most widely supported)
* Polygon (lower fees)
* Arbitrum
* Other options

***

## Setting Your Split

Choose what percentage goes where:

| Example         | Bank | Stablecoin |
| --------------- | ---- | ---------- |
| All traditional | 100% | 0%         |
| All stablecoin  | 0%   | 100%       |
| Conservative    | 80%  | 20%        |
| Balanced        | 50%  | 50%        |
| Crypto-forward  | 20%  | 80%        |

You can adjust your split at any time before each pay cycle.

***

## Things to Consider

### Benefits of Stablecoin

* Instant settlement
* Access to crypto ecosystem
* Potential for DeFi yields
* No bank account needed

### Considerations

* You'll need a crypto wallet
* Stablecoins are digital assets
* Tax implications may differ
* Network fees may apply for transfers

***

## Changing Your Preference

You can update your payout preference at any time:

1. Go to **Settings** > **Payroll**
2. Update your split or method
3. Changes apply to the next pay cycle

**Note:** Changes made after payroll processing begins apply to the following cycle.

***

## Tax Implications

<Warning>
  Stablecoin compensation is taxable income, just like traditional pay. Toku handles withholding the same way regardless of payment method. Consult a tax professional for specific advice.
</Warning>

***

<Tip>
  **Payroll Employee Guide** — Step 1 of 3. [Next: Setting Up Your Wallet](/payroll/user/setting-up-wallet)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Set Up Your Wallet" icon="wallet" href="/payroll/user/setting-up-wallet">
    Add your wallet address
  </Card>

  <Card title="Understanding Payslips" icon="file-lines" href="/payroll/user/understanding-payslip">
    Learn to read your payslip
  </Card>
</CardGroup>


# Setting Up Your Wallet
Source: https://docs.toku.com/payroll/user/setting-up-wallet

Add a wallet to receive stablecoin payments

## Overview

To receive stablecoin payments, you need to provide a wallet address. This guide helps you set up and connect a wallet.

***

## Getting a Wallet

If you don't have a crypto wallet, you'll need to create one.

### Recommended Wallets

<CardGroup>
  <Card title="MetaMask" icon="fox">
    Browser extension and mobile app. Works with Ethereum and compatible networks.
  </Card>

  <Card title="Coinbase Wallet" icon="wallet">
    Mobile app from Coinbase. Easy setup, beginner-friendly.
  </Card>

  <Card title="Rainbow" icon="rainbow">
    Mobile app with clean interface. Ethereum and Layer 2 support.
  </Card>

  <Card title="Phantom" icon="ghost">
    For Solana network. Browser extension and mobile app.
  </Card>
</CardGroup>

***

## Creating a Wallet

<Steps>
  <Step title="Download the wallet app">
    Get your chosen wallet from the official source (app store or official website).
  </Step>

  <Step title="Create a new wallet">
    Follow the app's setup process to create a new wallet.
  </Step>

  <Step title="Secure your recovery phrase">
    Write down your recovery phrase and store it safely. This is critical — if you lose it, you lose access to your funds.
  </Step>

  <Step title="Set a password">
    Create a strong password for the wallet app.
  </Step>

  <Step title="Get your address">
    Find your wallet address (starts with 0x for Ethereum, or other formats for other networks).
  </Step>
</Steps>

***

## Adding Your Wallet to Toku

<Steps>
  <Step title="Navigate to Wallets">
    In Toku, go to **Settings** > **Wallets**
  </Step>

  <Step title="Click Add Wallet">
    Select **Add Wallet**
  </Step>

  <Step title="Select network">
    Choose the network that matches your wallet:

    * Ethereum
    * Polygon
    * Arbitrum
    * etc.
  </Step>

  <Step title="Enter your address">
    Paste your wallet address carefully. Double-check it's correct.
  </Step>

  <Step title="Verify ownership">
    Complete any required verification (varies by setup).
  </Step>
</Steps>

***

## Wallet Address Tips

<Warning>
  **Triple-check your wallet address!** Crypto sent to the wrong address cannot be recovered.
</Warning>

### Do

* Copy and paste — don't type manually
* Verify the first and last several characters match
* Use a self-custody wallet (not an exchange)
* Keep your recovery phrase safe and private

### Don't

* Share your private key or recovery phrase with anyone
* Use an exchange deposit address (funds may be lost)
* Rely on memory — always verify the address

***

## Network Matching

Make sure your wallet supports the network your employer uses:

| Employer Uses    | You Need                            |
| ---------------- | ----------------------------------- |
| USDC on Ethereum | Ethereum wallet address             |
| USDC on Polygon  | Same address works (EVM compatible) |
| USDC on Solana   | Solana wallet address               |

Most EVM-compatible networks (Ethereum, Polygon, Arbitrum) use the same address format.

***

## Viewing Your Payments

After receiving stablecoin payments:

1. Open your wallet app
2. View your balance
3. See transaction history
4. The payment should appear within minutes

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="I don't see my payment in my wallet">
    Make sure you're viewing the correct network and token. You may need to add the stablecoin token to your wallet's token list.
  </Accordion>

  <Accordion title="I entered the wrong address">
    If you haven't received a payment yet, update your address immediately. If a payment was already sent to the wrong address, contact support — recovery depends on the situation.
  </Accordion>

  <Accordion title="What if I want to change wallets?">
    Add a new wallet in Toku and set it as your primary. Payments will go to the new address starting with the next pay cycle.
  </Accordion>
</AccordionGroup>

***

<Tip>
  **Payroll Employee Guide** — Step 2 of 3. [Previous: Choosing Your Payout Method](/payroll/user/choosing-payout-method) | [Next: Understanding Your Payslip](/payroll/user/understanding-payslip)
</Tip>

## Next Steps

<Card title="Understanding Your Payslip" icon="file-lines" href="/payroll/user/understanding-payslip">
  Learn to read your payslip
</Card>


# Understanding Your Payslip
Source: https://docs.toku.com/payroll/user/understanding-payslip

How to read your payslip with stablecoin payments

## Overview

Your payslip shows everything about your pay for each period, including both traditional and stablecoin payments.

***

## Payslip Sections

### Earnings

| Line Item          | Description                         |
| ------------------ | ----------------------------------- |
| **Regular Pay**    | Your standard salary for the period |
| **Overtime**       | Any overtime compensation           |
| **Bonus**          | One-time bonuses                    |
| **Other Earnings** | Commissions, stipends, etc.         |
| **Gross Pay**      | Total before deductions             |

### Deductions

| Line Item            | Description                      |
| -------------------- | -------------------------------- |
| **Federal Tax**      | Federal income tax withholding   |
| **State Tax**        | State income tax (if applicable) |
| **Local Tax**        | Local taxes (if applicable)      |
| **Social Security**  | FICA - Social Security           |
| **Medicare**         | FICA - Medicare                  |
| **Benefits**         | Health insurance, etc.           |
| **401(k)**           | Retirement contributions         |
| **Total Deductions** | Sum of all deductions            |

### Net Pay

| Line Item              | Description           |
| ---------------------- | --------------------- |
| **Net Pay**            | Your take-home amount |
| **Bank Deposit**       | Amount to your bank   |
| **Stablecoin Payment** | Amount in stablecoins |

***

## Stablecoin Payment Details

Your payslip shows:

| Field                 | Description                          |
| --------------------- | ------------------------------------ |
| **Stablecoin Amount** | How much you receive in stablecoins  |
| **USD Value**         | Dollar equivalent at time of payment |
| **Stablecoin Type**   | USDC, USDT, etc.                     |
| **Network**           | Ethereum, Polygon, etc.              |
| **Wallet Address**    | Where it was sent                    |
| **Transaction Hash**  | Blockchain reference                 |

***

## Example Payslip

```
PAY PERIOD: Jan 1 - Jan 15, 2024
PAY DATE: Jan 20, 2024

EARNINGS
  Regular Pay                    $5,000.00
  Gross Pay                      $5,000.00

DEDUCTIONS
  Federal Tax                      $750.00
  State Tax                        $250.00
  Social Security                  $310.00
  Medicare                          $72.50
  Health Insurance                 $200.00
  401(k)                           $250.00
  Total Deductions               $1,832.50

NET PAY                          $3,167.50

PAYMENT BREAKDOWN
  Bank Deposit (60%)             $1,900.50
  Stablecoin (40%)               $1,267.00

STABLECOIN DETAILS
  Amount: 1,267.00 USDC
  Network: Polygon
  Wallet: 0x1234...5678
  Tx Hash: 0xabcd...efgh
```

***

## Accessing Your Payslip

<Steps>
  <Step title="Log in to Toku">
    Access your employee portal
  </Step>

  <Step title="Navigate to Payslips">
    Click **Payroll** > **Payslips**
  </Step>

  <Step title="Select pay period">
    Choose the pay period you want to view
  </Step>

  <Step title="Download or print">
    Export as PDF if needed
  </Step>
</Steps>

***

## Verifying Your Stablecoin Payment

To confirm your stablecoin payment:

1. Find the transaction hash on your payslip
2. Go to a block explorer (Etherscan, Polygonscan, etc.)
3. Search for the transaction hash
4. View the transaction details and confirmation

***

## Year-End Documents

At year end, you'll receive:

* **W-2** — Annual wage and tax statement
* **Payment Summary** — Total payments received
* **Stablecoin Summary** — Total stablecoin payments

These documents are available in **Documents** > **Tax Documents**.

***

## Questions?

<CardGroup>
  <Card title="Payroll FAQ" icon="circle-question" href="/payroll/faq">
    Common questions
  </Card>

  <Card title="Contact Support" icon="headset" href="/getting-started/support">
    Get help
  </Card>
</CardGroup>

***

<Tip>
  **Payroll Employee Guide** — Step 3 of 3. [Previous: Setting Up Your Wallet](/payroll/user/setting-up-wallet)
</Tip>


# Adding Recipients
Source: https://docs.toku.com/tga/client/adding-recipients

Onboard employees and manage their roles in your organization

## Overview

Recipients are the people who receive token grants. Before creating grants, you need to add recipients to your organization and assign them roles.

***

## Adding a Single Recipient

<Steps>
  <Step title="Navigate to Users">
    Go to the admin sidebar and click **Users** or navigate to the org's user management page.
  </Step>

  <Step title="Click Add User">
    Click the **Add User** button.
  </Step>

  <Step title="Fill in details">
    * **Email** (required) — Must be unique across the organization
    * **First Name** and **Last Name** (required)
    * **Role** — Usually `RECIPIENT` for grant recipients
    * **External Employee ID** — Your HRIS identifier (optional but recommended for API integrations)
    * **Country** — Recipient's country of employment
    * **Employment Type** — Full-time, part-time, contractor, etc.
  </Step>

  <Step title="Save">
    Click **Save**. The recipient receives an activation email.
  </Step>
</Steps>

<Tip>
  **API:** Use [Create User Role in Org](/api/employees/create-user-role-in-org) to add recipients programmatically.
</Tip>

***

## Bulk Adding Recipients

For large teams, use the bulk upload feature:

<Steps>
  <Step title="Go to Bulk Upload">
    Navigate to **Bulk Upload** → **Recipients** tab.
  </Step>

  <Step title="Download the template">
    Click **Download Template** to get the CSV format.
  </Step>

  <Step title="Fill and upload">
    Add your recipients to the CSV and upload it.
  </Step>

  <Step title="Review">
    Fix any validation errors and submit.
  </Step>
</Steps>

***

## Roles

| Role               | Description                | Access                                           |
| ------------------ | -------------------------- | ------------------------------------------------ |
| `RECIPIENT`        | Grant recipient / employee | View grants, manage wallet, see vesting schedule |
| `CLIENT_ORG_ADMIN` | Organization administrator | Full access to all features                      |
| `PAYROLL_ADMIN`    | Payroll operations         | Access to payroll and settlement                 |
| `FINANCE_ADMIN`    | Financial reporting        | Access to reports and payments                   |
| `MANAGER`          | Team manager               | Manager-level access for direct reports          |

***

## Updating Recipients

Update recipient details from the user management page or via API:

<Tip>
  **API:** Use [Update User Role in Org](/api/employees/update-user-role-in-org) for single updates, or [Batch Update Roles](/api/employees/batch-update-roles) for bulk changes.
</Tip>

***

## HRIS Integration

If you use an HRIS system (ADP, Workday, UKG), you can sync employees automatically. Set the `externalEmployeeID` to match your HRIS identifier for seamless mapping between systems.

<CardGroup>
  <Card title="ADP Integration" icon="circle-nodes" href="/integrations/adp">
    Sync employees from ADP
  </Card>

  <Card title="Workday Integration" icon="circle-nodes" href="/integrations/workday">
    Sync employees from Workday
  </Card>
</CardGroup>


# Bulk Upload Grants
Source: https://docs.toku.com/tga/client/bulk-upload-grants

Upload grants, recipients, wallets, and more via CSV

## Overview

The Bulk Upload interface lets you import large datasets via CSV files. It supports multiple upload types from a single page with smart column matching and inline validation.

***

## Supported Upload Types

| Type                             | Description                                   |
| -------------------------------- | --------------------------------------------- |
| **Recipients**                   | Add employees/recipients to your organization |
| **Grants**                       | Create grants for existing recipients         |
| **Update Grants**                | Modify fields on existing grants              |
| **Wallets**                      | Add wallets for recipients                    |
| **Multiple Wallets**             | Add multiple wallets per recipient            |
| **Grant Templates**              | Import vesting schedule templates             |
| **Custom Vestings**              | Upload custom vesting tranches                |
| **Bulk Update Vesting Tranches** | Modify vesting schedules in bulk              |
| **Settlements**                  | Import settlement data                        |
| **Lockups**                      | Upload lockup schedules                       |
| **Investors**                    | Add investor entities                         |
| **Distribution Processing**      | Process distribution batches                  |

***

## Upload Process

<Steps>
  <Step title="Select upload type">
    Choose the tab for the data type you want to upload.
  </Step>

  <Step title="Download template">
    Click **Download Template** to get a CSV with the correct column headers.
  </Step>

  <Step title="Fill in your data">
    Populate the CSV with your data. Required columns are marked in the template.
  </Step>

  <Step title="Upload the CSV">
    Drag and drop or click to select your CSV file.
  </Step>

  <Step title="Map columns">
    The system auto-matches columns. Review and correct any mismatches (e.g., "First Name" maps to `givenName`).
  </Step>

  <Step title="Review and fix errors">
    Invalid cells are highlighted in red with error messages. Fix them inline or re-upload.
  </Step>

  <Step title="Submit">
    Click **Submit** to process the upload.
  </Step>
</Steps>

***

## Grant CSV Fields

| Column                 | Required | Description                     |
| ---------------------- | -------- | ------------------------------- |
| `email`                | Yes      | Recipient's email address       |
| `grantName`            | Yes      | Name for the grant              |
| `grantAmount`          | Yes      | Number of token units           |
| `grantConfigurationID` | No       | ID of the grant config template |
| `grantDate`            | No       | Date the grant was issued       |
| `vestingStartDate`     | No       | When vesting begins             |
| `pricePerUnit`         | No       | Token price at grant date       |
| `currency`             | No       | Price currency code             |
| `tags`                 | No       | Comma-separated tags            |

***

## API Alternative

For programmatic bulk operations:

<CardGroup>
  <Card title="Batch Update Roles" icon="users" href="/api/employees/batch-update-roles">
    Update multiple employees at once
  </Card>

  <Card title="Bulk Upload Wallets" icon="wallet" href="/api/wallets/bulk-upload-wallets">
    Upload multiple wallets via API
  </Card>
</CardGroup>


# Cap Table Management
Source: https://docs.toku.com/tga/client/cap-table-management

Track token ownership and grants across your organization

## Overview

The cap table in TGA provides a complete view of token ownership, including all grants, vesting status, and distributions.

***

## Viewing the Cap Table

Navigate to **Cap Table** from the sidebar to see:

* **Total tokens** allocated across all grants
* **Vested tokens** by holder
* **Unvested tokens** still in vesting periods
* **Distributed tokens** already sent to recipients

***

## Cap Table Views

### By Holder

See ownership grouped by individual:

* Name and email
* Total grants
* Vested and unvested amounts
* Percentage of total allocation

### By Grant Type

See ownership by grant type:

* RTU totals
* Option pools
* Warrant allocations
* Bonus awards

### By Department

If department data is available:

* Engineering allocation
* Sales allocation
* Executive allocation
* Etc.

***

## Key Metrics

| Metric               | Description                           |
| -------------------- | ------------------------------------- |
| **Fully Diluted**    | Total tokens if all grants fully vest |
| **Currently Vested** | Tokens that have vested to date       |
| **Outstanding**      | Vested but not yet distributed        |
| **Distributed**      | Tokens already sent to recipients     |
| **Forfeited**        | Tokens from cancelled grants          |

***

## Tracking Changes

### New Grants

When a grant is created, the cap table updates to show:

* Increased allocation to the recipient
* Updated totals for the grant type

### Vesting Events

As tokens vest:

* Unvested decreases
* Vested increases
* No change to total allocation

### Distributions

When tokens are distributed:

* Distributed amount increases
* Outstanding amount decreases

### Cancellations

When a grant is cancelled:

* Unvested tokens are forfeited
* Forfeited total increases

***

## Filtering and Search

Use filters to find specific information:

* **Date range** — View cap table as of a specific date
* **Grant type** — Filter by RTU, Options, etc.
* **Status** — Active, completed, or cancelled
* **Recipient** — Search by name or email

***

## Exporting Cap Table

Export the cap table for external use:

1. Apply any desired filters
2. Click **Export**
3. Choose format (CSV, Excel, PDF)
4. Download the file

***

## Historical Views

View the cap table at any point in time:

1. Navigate to **Cap Table**
2. Click **As of Date**
3. Select the date
4. View the cap table as it existed on that date

Useful for:

* Board meetings
* Audit requests
* Historical comparisons

***

<Tip>
  **TGA Client Guide** — Step 6 of 6. [Previous: Reporting & Compliance](/tga/client/reporting-and-compliance)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Reporting" icon="chart-bar" href="/tga/client/reporting-and-compliance">
    Generate detailed reports
  </Card>

  <Card title="TGA FAQ" icon="circle-question" href="/tga/faq">
    Common questions
  </Card>
</CardGroup>


# Creating Grants
Source: https://docs.toku.com/tga/client/creating-grants

Issue token grants to employees and recipients

## Overview

Create token grants to award equity to your team. Each grant specifies the recipient, token amount, vesting schedule, and grant configuration.

***

## Creating a Single Grant

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Navigate to Grants">
        Click **Grants** in the sidebar.
      </Step>

      <Step title="Click New Grant">
        Select **New Grant** to open the creation form.
      </Step>

      <Step title="Select grant configuration">
        Choose from your configured grant types (RTU, RTA, TPA, or TOKEN\_BONUS). See [Grant Configurations](/tga/client/grant-configurations) to set these up.
      </Step>

      <Step title="Enter grant details">
        * **Recipient** — Select or search by email
        * **Grant amount** — Number of token units
        * **Grant name** — Descriptive name
        * **Grant date** — When the grant was issued
        * **Vesting start date** — When vesting begins
        * **Vesting schedule** — Select a template or configure custom
        * **Tags** — Optional categorization
      </Step>

      <Step title="Review and create">
        Review the summary and click **Create Grant**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    Use the [Add Single Grant](/api/grants/add-single-grant) endpoint:

    ```bash theme={null}
    curl -X POST https://app.toku.com/api/tokuApi/v1/addSingleGrant \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "x-role-type: CLIENT_ORG_ADMIN" \
      -H "Content-Type: application/json" \
      -d '{
        "grantName": "Q1 2026 Token Grant - Jane Smith",
        "grantConfigurationID": "config-uuid",
        "grantAmount": 50000,
        "recipientID": "role-in-org-uuid",
        "vestingStartDate": "2026-01-01T00:00:00.000Z",
        "vestingFrequencyType": "MONTHLY",
        "vestingPeriods": 48,
        "vestingCliffPeriods": 12,
        "vestingCliffPercentage": 25,
        "tags": ["engineering", "2026"]
      }'
    ```

    For new hires, use [Create Grant for New Hire](/api/grants/create-grant-for-new-hire) to create the user and grant in one call.
  </Tab>
</Tabs>

***

## Grant Status Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING : Grant created
    PENDING --> ACCEPTED : Recipient accepts
    PENDING --> REJECTED : Recipient declines
    ACCEPTED --> COMPLETED : Fully vested
    ACCEPTED --> TERMINATED : Admin terminates
    ACCEPTED --> MARKED_FOR_FUTURE_TERMINATION : Future termination scheduled
    TERMINATED --> ACCEPTED : Termination reverted
```

| Status                          | Description                            |
| ------------------------------- | -------------------------------------- |
| `PENDING`                       | Created, awaiting recipient acceptance |
| `ACCEPTED`                      | Accepted and actively vesting          |
| `COMPLETED`                     | All vesting periods complete           |
| `TERMINATED`                    | Terminated early                       |
| `MARKED_FOR_FUTURE_TERMINATION` | Termination scheduled for future date  |
| `PAUSED`                        | Vesting temporarily paused             |
| `REJECTED`                      | Declined by recipient                  |

***

## Bulk Grant Creation

For multiple grants, use [Bulk Upload](/tga/client/bulk-upload-grants):

1. Navigate to **Bulk Upload** → **Grants** tab
2. Download the CSV template
3. Fill in grant details for each recipient
4. Upload and review
5. Submit

***

## Updating Grants

Edit pending grants before they're accepted:

* Change token amount, vesting dates, or tags
* Update grant configuration
* Modify recipient assignment

<Tip>
  After acceptance, use [Terminate Grant](/api/grants/terminate-grant) to end a grant, or create a new grant with updated terms.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Grant Configurations" icon="gear" href="/tga/client/grant-configurations">
    Set up grant type templates
  </Card>

  <Card title="Vesting Schedules" icon="calendar" href="/tga/client/managing-vesting-schedules">
    Configure vesting schedules
  </Card>

  <Card title="Terminations" icon="scissors" href="/tga/client/terminations">
    Handle employee departures
  </Card>

  <Card title="Bulk Upload" icon="upload" href="/tga/client/bulk-upload-grants">
    Import grants via CSV
  </Card>
</CardGroup>


# Custody Integrations
Source: https://docs.toku.com/tga/client/custody-overview

Connect custody providers for secure token settlement

## Overview

Custody integrations enable automated token settlement through institutional-grade custody providers. When vestings are ready for distribution, settlements are routed through your connected provider.

***

## Supported Providers

<CardGroup>
  <Card title="Anchorage Digital" icon="shield-halved">
    Institutional-grade custody for digital assets with Anchorage Digital.
  </Card>

  <Card title="Fireblocks" icon="fire">
    Secure digital asset infrastructure for custody, transfer, and settlement.
  </Card>

  <Card title="Safe (Gnosis)" icon="vault">
    Multi-signature smart contract wallet for secure on-chain custody.
  </Card>

  <Card title="Off Platform" icon="building">
    Manage custody independently outside of the Toku platform. No API credentials required.
  </Card>
</CardGroup>

***

## Connecting a Provider

### During Onboarding

During the initial setup checklist, click **Connect** next to "Connect custody integration" on the dashboard. A modal presents the four provider options — select one to begin the setup flow.

### From Settings

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Integrations** from the sidebar.
  </Step>

  <Step title="Select your provider">
    Click on the custody provider you want to connect.
  </Step>

  <Step title="Enter credentials">
    Provide the required API keys and configuration:

    * **Fireblocks**: API key, secret key, vault account ID
    * **Anchorage**: API key, organization ID
    * **Safe (Gnosis)**: Safe wallet address
    * **Off Platform**: No credentials required — select to acknowledge custody is managed externally
  </Step>

  <Step title="Test connection">
    For Fireblocks, Anchorage, and Safe, the system verifies connectivity before saving.
  </Step>

  <Step title="Configure settlement settings">
    Set default vault accounts, signing policies, and notification preferences.
  </Step>
</Steps>

***

## Settlement Flow by Provider

### Fireblocks

1. Settlement submitted to Fireblocks vault
2. Policy engine evaluates the transaction
3. Required signers approve in Fireblocks console
4. Transaction broadcasts on-chain

### Anchorage

1. Settlement submitted to Anchorage
2. Anchorage processes the transfer
3. Transaction confirms on-chain

### Safe (Multisig)

1. Transaction proposal created in Safe
2. Required signers approve the transaction
3. Final signer executes the transaction on-chain

***

## Related

<CardGroup>
  <Card title="Settlements" icon="file-invoice-dollar" href="/tga/client/settlements">
    Learn about the full settlement process
  </Card>

  <Card title="Wallet Setup" icon="wallet" href="/tga/client/wallet-setup">
    Configure recipient wallets
  </Card>
</CardGroup>


# Grant Configurations
Source: https://docs.toku.com/tga/client/grant-configurations

Create and manage grant type templates for your organization

## Overview

Grant configurations define the types of token grants your organization issues. Each configuration specifies the grant type, signing requirements, and default settings. All grants are created from a configuration template.

***

## Grant Types

| Type                                | Description                             | Common Use                           |
| ----------------------------------- | --------------------------------------- | ------------------------------------ |
| **RTU** (Restricted Token Units)    | Token units that vest over time         | Standard employee token compensation |
| **RTA** (Restricted Token Awards)   | Token awards with restrictions          | Performance-based awards             |
| **TPA** (Token Purchase Agreements) | Right to purchase tokens at a set price | Similar to stock options             |
| **TOKEN\_BONUS**                    | One-time token bonus                    | Signing bonuses, spot awards         |

***

## Creating a Configuration

<Steps>
  <Step title="Navigate to Grant Configurations">
    Go to **Grants** → **Grant Configurations** in the sidebar.
  </Step>

  <Step title="Click Create">
    Click **Create Grant Configuration** to open the setup form.
  </Step>

  <Step title="Select the grant type">
    Choose RTU, RTA, TPA, or TOKEN\_BONUS.
  </Step>

  <Step title="Name the configuration">
    Give it a descriptive name (e.g., "Standard 4-Year RTU" or "Q1 Bonus").
  </Step>

  <Step title="Configure signing tabs">
    Set up any document signing requirements for grants of this type.
  </Step>

  <Step title="Save">
    Click **Save** to create the configuration.
  </Step>
</Steps>

***

## Managing Configurations

From the Grant Configurations page, you can:

* **Edit** — Update the name, type, or signing requirements
* **View grants** — See all grants created with this configuration
* **Archive** — Deactivate a configuration (existing grants are not affected)

***

## Using Configurations via API

<Tip>
  **API:** Use [List Grant Configurations](/api/grants/list-grant-configurations) to retrieve all configurations. Pass the `grantConfigurationID` when creating grants via [Add Single Grant](/api/grants/add-single-grant).
</Tip>


# Managing Vesting Schedules
Source: https://docs.toku.com/tga/client/managing-vesting-schedules

Configure and manage vesting schedules for token grants

## Overview

Vesting schedules determine when recipients earn their tokens. TGA provides pre-built templates and a custom vesting builder.

***

## Pre-Built Templates

| Template                 | Cliff            | Vesting                     | Total     |
| ------------------------ | ---------------- | --------------------------- | --------- |
| **4-Year, 1-Year Cliff** | 25% at 12 months | 2.08% monthly for 36 months | 48 months |
| **3-Year, No Cliff**     | None             | 2.78% monthly               | 36 months |
| **2-Year Quarterly**     | None             | 12.5% per quarter           | 24 months |
| **1-Year Monthly**       | None             | 8.33% monthly               | 12 months |

***

## Creating a Vesting Template

<Steps>
  <Step title="Navigate to Vesting Schedules">
    Go to **Vesting Schedules** in the sidebar.
  </Step>

  <Step title="Click Create Template">
    Select **Create Template** to open the builder.
  </Step>

  <Step title="Choose a preset or custom">
    Pick a pre-built template or select **Custom** to define your own tranches.
  </Step>

  <Step title="Configure tranches">
    For custom schedules, define each vesting tranche:

    * **Percentage** — What portion of the grant vests
    * **Time period** — When the tranche vests (months from start)
    * **Type** — Cliff (all-at-once) or linear (gradual)
  </Step>

  <Step title="Save">
    Name the template and save for reuse across grants.
  </Step>
</Steps>

***

## Vesting Parameters

| Parameter            | Description                       | Options                      |
| -------------------- | --------------------------------- | ---------------------------- |
| **Vesting Period**   | Total months for full vesting     | 1–120 months                 |
| **Cliff**            | Initial waiting period            | 0–24 months                  |
| **Cliff Percentage** | Percentage that vests at cliff    | 0–100%                       |
| **Frequency**        | How often tokens vest after cliff | Monthly, Quarterly, Annually |

***

## How Vesting Works

### Example: 4-Year with 1-Year Cliff

For a 10,000 token grant starting January 2026:

| Date     | Event            | Tokens      | Cumulative |
| -------- | ---------------- | ----------- | ---------- |
| Jan 2026 | Grant starts     | 0           | 0          |
| Jan 2027 | **Cliff vests**  | 2,500 (25%) | 2,500      |
| Feb 2027 | Monthly vest     | \~208       | 2,708      |
| Mar 2027 | Monthly vest     | \~208       | 2,917      |
| ...      | ...              | ...         | ...        |
| Jan 2030 | **Fully vested** | \~208       | 10,000     |

***

## Unified Schedule Manager

The Schedule Manager provides a single view of all vesting and distribution activity across 6 tabs:

1. **Distribution Config** — Set FMV mode and variance thresholds
2. **Pending Approval** — Approve vesting events as they occur
3. **Tax Grouping** — Assign tax details to approved vestings
4. **Tax Finalization** — Review and finalize tax calculations
5. **Ready for Settlement** — Vestings eligible for distribution
6. **Settlements** — Pending and completed settlements

***

## Modifying Vesting

* **Before acceptance**: Vesting schedules can be changed freely
* **After acceptance**: Terminate the grant and create a new one with updated terms
* **Bulk updates**: Use [Bulk Upload](/tga/client/bulk-upload-grants) → **Bulk Update Vesting Tranches** tab

***

## Next Steps

<CardGroup>
  <Card title="Token Distributions" icon="share-nodes" href="/tga/client/token-distributions">
    Process vested tokens
  </Card>

  <Card title="Settlements" icon="file-invoice-dollar" href="/tga/client/settlements">
    Full settlement workflow
  </Card>
</CardGroup>


# Onboarding Checklist
Source: https://docs.toku.com/tga/client/onboarding-checklist

Complete your TGA account setup in 6 steps

## Overview

When you first log in as a Client Admin, the TGA dashboard shows a setup checklist that walks you through everything needed to start managing token grants. Complete all 6 steps to fully configure your organization.

***

## Step 1: Add Employees to People Directory

Upload your employees who will receive token grants. You can add them one at a time or upload a CSV.

<Steps>
  <Step title="Open the Add Employees modal">
    Click **Upload** next to "Add employees to people directory" in the checklist. The **Add Employees** modal opens.
  </Step>

  <Step title="Choose your method">
    * **Manual Entry** tab: Add employees one by one — enter First name, Last name, and Email address. Click **Add Another** to add more rows.
    * **CSV Upload** tab: Upload a spreadsheet with columns for first name, last name, email, and optional fields like department, country, and external employee ID.
  </Step>

  <Step title="Submit">
    Click **Add Employees** to save. The step is marked complete and the button changes to **Manage**.
  </Step>
</Steps>

<Tip>
  **API:** Use [Create User Role in Org](/api/employees/create-user-role-in-org) to add employees programmatically, or [Batch Update Roles](/api/employees/batch-update-roles) for bulk operations.
</Tip>

***

## Step 2: Create a Grant Configuration

Define what type of token grants your organization issues.

<Steps>
  <Step title="Open the Create Grant Type modal">
    Click **Create** next to "Create a grant configuration" in the checklist. The **Create Grant Type** modal opens.
  </Step>

  <Step title="Select a grant type">
    Choose from:

    * **RTU** — Restricted Token Unit: Tokens subject to vesting and restrictions
    * **RTA** — Restricted Token Award: Token awards with conditional restrictions
    * **Token Bonus** — Performance-based token rewards
    * **TPA** — Token Purchase Agreement: Agreements for token purchases
    * **Other** — Enter a custom grant type name
  </Step>

  <Step title="Confirm">
    Click **Create Grant Type** to save. The step is marked complete and the button changes to **Manage**. You can create additional grant types later from **Grants → Grant Configurations**.
  </Step>
</Steps>

<Tip>
  **API:** Use [List Grant Configurations](/api/grants/list-grant-configurations) to retrieve your configurations.
</Tip>

***

## Step 3: Configure Vesting Schedules

Set up how tokens vest over time using pre-built templates or a custom schedule.

**Pre-built templates:**

| Template                 | Description                                                            |
| ------------------------ | ---------------------------------------------------------------------- |
| **4-Year, 1-Year Cliff** | Standard startup vesting — 25% at 12 months, then monthly over 3 years |
| **3-Year, No Cliff**     | Equal monthly vesting — \~2.78% per month for 36 months                |
| **2-Year Quarterly**     | 8 equal quarterly tranches — 12.5% every 3 months                      |
| **1-Year Monthly**       | 12 equal monthly tranches — \~8.33% per month                          |
| **Custom Schedule**      | Full control over frequency, tranches, and lockup periods              |

<Steps>
  <Step title="Open the Configure Vesting Schedule modal">
    Click **Create** next to "Configure vesting schedules" in the checklist. The **Configure Vesting Schedule** modal opens showing all available templates.
  </Step>

  <Step title="Select a template">
    Click on a pre-built template card to immediately create it, or click **Custom Schedule** to open the full vesting builder and define your own tranches.
  </Step>
</Steps>

Selecting a template immediately saves the schedule. The step is marked complete and the button changes to **Manage**.

***

## Step 4: Create Grants for Employees

Assign token grants to your employees. This step unlocks after completing steps 1–3.

<Steps>
  <Step title="Open the Create Grants modal">
    Click **Upload** next to "Create grants for employees" in the checklist. The **Create Grants** modal opens.
  </Step>

  <Step title="Add grants">
    * **Manual Entry** tab: Fill in per-employee grant fields:
      * **Employee Email** — select from your people directory
      * **Grant Name** — defaults to current quarter (e.g. "Q1 2026 Grant")
      * **Grant Amount** — number of tokens
      * **Grant Type** — e.g. RTU Grant
      * **Asset Type** — TOKEN or FIAT
      * **Vesting Start Date** — defaults to today
      * **Grant Date** — defaults to today
      * **Grant Currency** — defaults to USD
      * **Vesting Template** — select from your configured schedules
      * **Section 83(b) Eligible** — Yes or No
    * **CSV Upload** tab: Upload a spreadsheet with the above fields for bulk grant creation.

    Click **Add Another Grant** to add multiple grants in one submission.
  </Step>

  <Step title="Submit">
    Click **Create Grants** to save all grants.
  </Step>
</Steps>

<Tip>
  **API:** Use [Add Single Grant](/api/grants/add-single-grant) or [Create Grant for New Hire](/api/grants/create-grant-for-new-hire) to create grants programmatically.
</Tip>

***

## Step 5: Set Up Wallet Settings

Configure which blockchain networks and token contract your organization uses for settlements.

<Steps>
  <Step title="Open Wallet Settings">
    Click **Set Up** next to "Set up wallet settings" in the checklist. The **Wallet Settings** modal opens with two sections: **Networks** and **Token Contract Address**.
  </Step>

  <Step title="Select networks">
    Click one or more network pills to add them. Supported networks:
    **Ethereum**, **Base**, **Solana**, **Polygon**, **Arbitrum**, **Optimism**, **Avalanche**, or **Custom**.

    Added networks appear as a list below the pills. Click the trash icon to remove a network.
  </Step>

  <Step title="Set your token contract address">
    Enter your token's contract address in the **Token Contract Address** field and click **Save**. This is used for distributions and wallet verification.
  </Step>

  <Step title="Close">
    Click **Close** to exit the modal. The step is marked complete and the button changes to **Manage**.
  </Step>
</Steps>

<Tip>
  **API:** Use [Get Networks](/api/tokens-and-networks/get-networks) and [Update Token Address](/api/organization/update-token-address) to configure programmatically.
</Tip>

***

## Step 6: Connect Custody Integration

Connect your custody provider for secure token distribution.

<Steps>
  <Step title="Open the Connect Custody Integration modal">
    Click **Connect** next to "Connect custody integration" in the checklist. The **Connect Custody Integration** modal opens.
  </Step>

  <Step title="Select a custody provider">
    Choose one of the four options:

    <CardGroup>
      <Card title="Anchorage Digital" icon="shield-halved">
        Institutional-grade custody for digital assets with Anchorage Digital.
      </Card>

      <Card title="Fireblocks" icon="fire">
        Secure digital asset infrastructure for custody, transfer, and settlement.
      </Card>

      <Card title="Safe (Gnosis)" icon="vault">
        Multi-signature smart contract wallet for secure on-chain custody.
      </Card>

      <Card title="Off Platform" icon="building">
        Manage custody independently outside of the Toku platform.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Enter credentials (Anchorage, Fireblocks, or Safe)">
    Follow the inline setup dialog for your chosen provider. You'll need API keys and configuration details from your custody account. The system verifies the connection before saving.
  </Step>
</Steps>

<Note>
  **Off Platform** allows you to acknowledge that custody is managed outside of Toku without providing integration credentials. This is suitable for organizations handling settlements independently.
</Note>

***

## After Setup

Once all 6 steps are complete (100%), the checklist can be dismissed and you have full access to:

<CardGroup>
  <Card title="Grant Management" icon="award" href="/tga/client/creating-grants">
    Create, edit, terminate, and bulk upload grants
  </Card>

  <Card title="Distributions" icon="share-nodes" href="/tga/client/token-distributions">
    Manage vesting, settlements, and token distributions
  </Card>

  <Card title="Wallets" icon="wallet" href="/tga/client/wallet-setup">
    Manage recipient wallets and verification
  </Card>

  <Card title="Reports" icon="chart-line" href="/tga/client/reporting-and-compliance">
    Grant reports, activity logs, and compliance
  </Card>
</CardGroup>


# Reporting & Compliance
Source: https://docs.toku.com/tga/client/reporting-and-compliance

Generate reports and maintain compliance for token grants

## Overview

TGA provides comprehensive reporting tools to help you track grants, distributions, and maintain compliance with tax and accounting requirements.

***

## Available Reports

<CardGroup>
  <Card title="Grant Summary" icon="file-lines">
    Overview of all grants by status, type, and recipient
  </Card>

  <Card title="Vesting Report" icon="calendar">
    Upcoming and past vesting events
  </Card>

  <Card title="Distribution Report" icon="paper-plane">
    All token distributions with tax details
  </Card>

  <Card title="Cap Table" icon="chart-pie">
    Current ownership and token allocation
  </Card>
</CardGroup>

***

## Generating Reports

<Steps>
  <Step title="Navigate to Reports">
    Click **Reports** in the sidebar
  </Step>

  <Step title="Select report type">
    Choose the report you need
  </Step>

  <Step title="Set parameters">
    Configure date range and filters
  </Step>

  <Step title="Generate and export">
    Click **Generate** and download as CSV or PDF
  </Step>
</Steps>

***

## Report Types

### Grant Summary Report

Shows all grants in your organization:

* Recipient name and email
* Grant type and token amount
* Vesting schedule and progress
* Current status

### Vesting Report

Tracks vesting events:

* Upcoming vesting dates
* Tokens vesting per event
* Historical vesting data

### Distribution Report

Details all token distributions:

* Distribution date and amount
* Gross vs. net (after withholding)
* Transaction hash and status
* Recipient wallet address

### Tax Withholding Report

For tax compliance:

* Withholding amounts by recipient
* Tax jurisdiction breakdown
* Summary for remittance

***

## Compliance Features

### KYC Verification

TGA integrates with identity verification providers to ensure recipients complete KYC before claiming tokens.

* Recipients are prompted to verify identity
* Verification status shown on each grant
* Distributions blocked until KYC complete

### Tax Documentation

Generate tax documents for recipients:

* Token value at distribution
* Withholding amounts
* Supporting documentation

### Audit Trail

TGA maintains a complete audit trail:

* All grant creation and modification events
* Approval workflows
* Distribution records

***

## Scheduled Reports

Set up automatic report delivery:

1. Navigate to **Reports** > **Scheduled**
2. Select report type
3. Configure frequency (daily, weekly, monthly)
4. Add recipient email addresses
5. Save the schedule

***

## Accounting Integration

Export data for your accounting system:

* **CSV exports** with customizable fields
* **API access** for automated integration
* **Formatted reports** matching common accounting formats

***

<Tip>
  **TGA Client Guide** — Step 5 of 6. [Previous: Token Distributions](/tga/client/token-distributions) | [Next: Cap Table Management](/tga/client/cap-table-management)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Cap Table" icon="chart-pie" href="/tga/client/cap-table-management">
    Manage token ownership
  </Card>

  <Card title="TGA FAQ" icon="circle-question" href="/tga/faq">
    Common questions
  </Card>
</CardGroup>


# Setting Up Your Account
Source: https://docs.toku.com/tga/client/setting-up-your-account

Configure TGA for your organization

## Overview

Before creating grants, you'll need to set up your TGA account with your organization's details, token information, and custody integration.

***

## Initial Setup

<Steps>
  <Step title="Complete organization profile">
    Navigate to **Settings** > **Organization** and fill in:

    * Legal entity name
    * Business address
    * Tax identification number
    * Primary contact information
  </Step>

  <Step title="Add your token">
    Go to **Settings** > **Tokens** and configure:

    * Token name and symbol
    * Contract address
    * Blockchain network
    * Decimal places
  </Step>

  <Step title="Connect custody provider">
    Link your custody provider in **Settings** > **Integrations**:

    * Select your provider (Fireblocks, Anchorage, etc.)
    * Follow the authentication flow
    * Verify the connection
  </Step>

  <Step title="Invite team members">
    Add other admins in **Settings** > **Team**:

    * Enter email addresses
    * Assign appropriate roles
    * Send invitations
  </Step>
</Steps>

***

## Token Configuration

### Adding Your Token

1. Navigate to **Settings** > **Tokens**
2. Click **Add Token**
3. Enter the token details:
   * **Name**: Your token's full name
   * **Symbol**: The ticker symbol (e.g., ABC)
   * **Contract Address**: The token contract address
   * **Network**: Ethereum, Polygon, Solana, etc.
4. Save and verify the token appears correctly

### Multiple Tokens

If your organization has multiple tokens, you can add each one separately. Grants can be created for any configured token.

***

## Team Roles

| Role        | Permissions                                    |
| ----------- | ---------------------------------------------- |
| **Admin**   | Full access to all TGA features                |
| **Finance** | View and process distributions, access reports |
| **Viewer**  | View-only access to grants and cap table       |

***

## Custody Integration

TGA integrates with leading custody providers:

<CardGroup>
  <Card title="Anchorage Digital" icon="shield-halved">
    Institutional-grade custody for digital assets
  </Card>

  <Card title="Fireblocks" icon="fire">
    Secure digital asset infrastructure for custody and settlement
  </Card>

  <Card title="Safe (Gnosis)" icon="vault">
    Multi-signature smart contract wallet for on-chain custody
  </Card>

  <Card title="Off Platform" icon="building">
    Manage custody independently outside of Toku
  </Card>
</CardGroup>

<Card title="Integration Setup" icon="arrow-right" href="/integrations/overview">
  Learn more about connecting custody providers
</Card>

***

<Tip>
  **TGA Client Guide** — Step 1 of 6. [Next: Creating Grants](/tga/client/creating-grants)
</Tip>

## Next Steps

<CardGroup>
  <Card title="Create Grants" icon="plus" href="/tga/client/creating-grants">
    Start issuing token grants
  </Card>

  <Card title="Vesting Schedules" icon="calendar" href="/tga/client/managing-vesting-schedules">
    Set up vesting templates
  </Card>
</CardGroup>


# Settlements
Source: https://docs.toku.com/tga/client/settlements

Process token distributions and settle vesting events

## Overview

When tokens vest, they need to be settled — meaning the actual tokens are transferred to the recipient's wallet. The settlement process involves tax calculation, approval, and execution through your custody provider.

***

## Settlement Workflow

```mermaid theme={null}
graph TD
    A[Token Vests] --> B[Pending Approval]
    B --> C[Tax Grouping]
    C --> D[Tax Finalization]
    D --> E[Ready for Settlement]
    E --> F[Settlement Execution]
    F --> G[Completed]
```

***

## Step 1: Pending Approval

When vesting events occur, they appear in the **Pending Approval** tab of the Schedule Manager. An admin must approve each vesting before it can proceed.

***

## Step 2: Tax Grouping

After approval, vestings move to **Tax Grouping**. Here you assign tax details:

* **Manual tax**: Enter tax amounts directly
* **Payroll tax**: Use tax details from your payroll provider
* **No tax**: Mark as tax-exempt

***

## Step 3: Tax Finalization

Tax details are reviewed and finalized. Admin can approve or reject tax calculations. Rejected items return to the Tax Grouping stage.

***

## Step 4: Ready for Settlement

Vestings with finalized tax details are ready for settlement. You can:

* **Batch settlements** — Process multiple vestings together
* **Select custody provider** — Choose Fireblocks, Anchorage, or Safe
* **Generate settlement documents** — Create proof-of-payment records

***

## Step 5: Execution

The settlement is executed through your connected custody provider:

* **Fireblocks**: Transaction submitted to Fireblocks vault
* **Anchorage**: Transaction submitted to Anchorage
* **Safe**: Multisig transaction created, requiring signer approvals

***

## Unified Schedule Manager

The Schedule Manager provides a single interface for the entire settlement flow with 6 tabs:

| Tab                  | Purpose                              |
| -------------------- | ------------------------------------ |
| Distribution Config  | Set FMV mode and variance thresholds |
| Pending Approval     | Approve vesting events               |
| Tax Grouping         | Assign tax details                   |
| Tax Finalization     | Review and finalize tax              |
| Ready for Settlement | Eligible for distribution            |
| Settlements          | Pending and completed settlements    |

***

## Related

<CardGroup>
  <Card title="Token Distributions" icon="share-nodes" href="/tga/client/token-distributions">
    Distribution overview and configuration
  </Card>

  <Card title="Custody Integrations" icon="vault" href="/tga/client/custody-overview">
    Set up custody providers for settlement execution
  </Card>
</CardGroup>


# Grant Terminations
Source: https://docs.toku.com/tga/client/terminations

Terminate and revert token grants when employees leave

## Overview

When an employee leaves or a grant needs to be cancelled, you can terminate their grants. Termination recalculates the vesting schedule — only tokens that have vested up to the termination date remain; future vestings are cancelled.

***

## Terminating a Single Grant

<Steps>
  <Step title="Navigate to the grant">
    Go to **Grants** and find the grant to terminate.
  </Step>

  <Step title="Click Terminate">
    Open the grant detail and click **Terminate Grant**.
  </Step>

  <Step title="Set the termination date">
    Choose the effective termination date. Vestings after this date will be cancelled.
  </Step>

  <Step title="Confirm">
    Review the impact and confirm. The grant status changes to `TERMINATED`.
  </Step>
</Steps>

<Tip>
  **API:** Use [Terminate Grant](/api/grants/terminate-grant) with the `grantID` and `terminationDate`.
</Tip>

***

## Terminating All Grants for an Employee

When an employee leaves, terminate all their active grants at once:

<Tip>
  **API:** Use [Terminate Employee Grants](/api/grants/terminate-employee-grants) with the `externalEmployeeID` and `terminationDate`. If `grantIDs` is omitted, all active grants are terminated.
</Tip>

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/terminateEmployeeGrants \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalEmployeeID": "EMP-001",
    "terminationDate": "2026-06-30T00:00:00.000Z"
  }'
```

**Response:**

```json theme={null}
{
  "terminatedGrantIDs": ["grant-uuid-1", "grant-uuid-2"],
  "alreadyTerminatedGrantIDs": []
}
```

***

## Bulk Termination

Terminate specific grants across multiple employees:

<Tip>
  **API:** Use [Terminate Grants (Bulk)](/api/grants/terminate-grants-bulk) with an array of `grantIDs` and `terminationDate`.
</Tip>

***

## Reverting a Termination

Made a mistake? Revert a termination to restore the grant to its previous status and regenerate future vestings.

<Steps>
  <Step title="Find the terminated grant">
    Filter grants by status `TERMINATED`.
  </Step>

  <Step title="Click Revert">
    Open the grant and click **Revert Termination**.
  </Step>

  <Step title="Confirm">
    The grant returns to its pre-termination status with vestings regenerated.
  </Step>
</Steps>

### Revert via API

**Single grant:**

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/revertGrantTermination \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{"grantID": "grant-uuid"}'
```

**All grants for an employee:**

```bash theme={null}
curl -X POST https://app.toku.com/api/tokuApi/v1/revertEmployeeGrants \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-role-type: CLIENT_ORG_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalEmployeeID": "EMP-001",
    "grantIDs": ["grant-uuid-1", "grant-uuid-2"]
  }'
```

***

## Grant Status After Termination

| Status                          | Meaning                                      |
| ------------------------------- | -------------------------------------------- |
| `TERMINATED`                    | Grant terminated, future vestings cancelled  |
| `MARKED_FOR_FUTURE_TERMINATION` | Termination scheduled for a future date      |
| `ACCEPTED`                      | Grant restored after revert (back to active) |

***

## Related API Endpoints

<CardGroup>
  <Card title="Terminate Grant" icon="scissors" href="/api/grants/terminate-grant">
    Terminate a single grant
  </Card>

  <Card title="Terminate Employee Grants" icon="user-minus" href="/api/grants/terminate-employee-grants">
    Terminate all grants for an employee
  </Card>

  <Card title="Revert Termination" icon="rotate-left" href="/api/grants/revert-grant-termination">
    Undo a termination
  </Card>

  <Card title="Revert Employee Grants" icon="rotate-left" href="/api/grants/revert-employee-grants">
    Bulk revert for an employee
  </Card>
</CardGroup>


# Token Distributions
Source: https://docs.toku.com/tga/client/token-distributions

Process and track token distributions to recipient wallets

## Overview

Token distributions send vested tokens from your organization to recipients' wallets through your connected custody provider. TGA handles the full flow from vesting through tax calculation to on-chain settlement.

***

## Distribution Views

### Upcoming Distributions

Shows vestings that are coming due. Monitor what's approaching and prepare for settlement.

### Historical Distributions

View completed distributions with transaction details, amounts, and on-chain confirmations.

***

## Distribution Workflow

```mermaid theme={null}
graph TD
    A[Token Vests] --> B[Admin Approves]
    B --> C[Tax Calculated]
    C --> D[Tax Finalized]
    D --> E[Settlement Created]
    E --> F{Custody Provider}
    F --> G[Fireblocks]
    F --> H[Anchorage]
    F --> I[Safe Multisig]
    G --> J[On-Chain Confirmation]
    H --> J
    I --> J
    J --> K[Distribution Complete]
```

<Steps>
  <Step title="Vesting occurs">
    Tokens vest according to the grant's schedule. Vested amounts appear in the **Pending Approval** queue.
  </Step>

  <Step title="Admin approves">
    Review and approve vesting events. Batch approve multiple vestings at once.
  </Step>

  <Step title="Tax calculation">
    Assign tax details — manual, from payroll, or mark as tax-exempt. Tax amounts are calculated based on FMV and jurisdiction rules.
  </Step>

  <Step title="Tax finalization">
    Review tax calculations and finalize. Rejected items return to tax grouping.
  </Step>

  <Step title="Settlement execution">
    Create settlement batches and route through your custody provider:

    * **Fireblocks** — Direct vault transaction
    * **Anchorage** — Institutional settlement
    * **Safe** — Multisig approval required
  </Step>

  <Step title="Confirmation">
    Track on-chain transaction status. Once confirmed, the distribution is complete.
  </Step>
</Steps>

***

## Batch Transactions

Process multiple settlements together for efficiency:

1. Navigate to **Batch Transactions**
2. Select vestings ready for settlement
3. Choose your custody provider
4. Submit the batch
5. Track status: Pending Allocation → Pending Execution → Executed

***

## Tax Withholding

TGA supports tax withholding during settlement:

| Detail           | Description                          |
| ---------------- | ------------------------------------ |
| **Gross tokens** | Total vested amount                  |
| **Withholding**  | Tokens held for tax obligations      |
| **Net tokens**   | Amount sent to recipient wallet      |
| **FMV**          | Fair market value at time of vesting |

***

## Settlement Documents

Generate proof-of-payment and tax documents:

* Settlement summaries per recipient
* Tax reference documents
* Distribution confirmation records

***

## Next Steps

<CardGroup>
  <Card title="Settlements" icon="file-invoice-dollar" href="/tga/client/settlements">
    Detailed settlement workflow
  </Card>

  <Card title="Custody Integrations" icon="vault" href="/tga/client/custody-overview">
    Connect custody providers
  </Card>

  <Card title="Reporting" icon="chart-line" href="/tga/client/reporting-and-compliance">
    Distribution reports
  </Card>
</CardGroup>


# Wallet Setup
Source: https://docs.toku.com/tga/client/wallet-setup

Add and manage recipient wallets for token distributions

## Overview

Before tokens can be distributed, recipients need to add their blockchain wallets. Wallets go through a verification process to ensure they are valid and owned by the recipient.

***

## Wallet Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Added: Recipient adds wallet
    Added --> TestSent: Admin sends test txn
    TestSent --> Verified: Recipient confirms receipt
    Verified --> Approved: Admin approves
    Approved --> Active: Ready for distributions
    Active --> Archived: Deactivated
    Archived --> Active: Reactivated
```

***

## Adding Wallets

Recipients can add wallets through the employee portal, or admins can add them on behalf of recipients.

**Required information:**

* **Wallet address** — The blockchain address
* **Network** — Which blockchain (Ethereum, Solana, etc.)
* **Wallet type** — Configured by the admin (e.g., "Hot Wallet", "Custody")

<Tip>
  **API:** Use [Add Wallet](/api/wallets/add-wallet) to add wallets programmatically, or [Bulk Upload Wallets](/api/wallets/bulk-upload-wallets) for multiple wallets.
</Tip>

***

## Wallet Verification

Wallet verification uses test transactions to confirm the recipient controls the address.

<Steps>
  <Step title="Admin initiates test transaction">
    Go to the wallet management page and click **Send Test Transaction** for the wallet.
  </Step>

  <Step title="System sends a small amount">
    A configurable amount of tokens is sent to the wallet address. The recipient receives an email notification.
  </Step>

  <Step title="Recipient confirms receipt">
    The recipient logs in and confirms they received the test transaction.
  </Step>

  <Step title="Admin approves">
    The admin reviews and approves the verified wallet.
  </Step>
</Steps>

<Tip>
  **API:** Use [Send Test Transaction](/api/wallets/send-test-transaction) to initiate verification, then [Approve Wallet Request](/api/wallets/approve-wallet-request) to approve.
</Tip>

***

## Managing Wallets

| Action         | Description                  | API                                                         |
| -------------- | ---------------------------- | ----------------------------------------------------------- |
| **Deactivate** | Move a wallet to historical  | [Deactivate Wallet](/api/wallets/deactivate-wallet)         |
| **Reactivate** | Restore a deactivated wallet | [Reactivate Wallet](/api/wallets/reactivate-wallet)         |
| **Reject**     | Reject a wallet submission   | [Reject Wallet](/api/wallets/reject-wallet)                 |
| **Cancel**     | Cancel a pending request     | [Cancel Wallet Request](/api/wallets/cancel-wallet-request) |

***

## Wallet Distribution

Once wallets are verified and approved, configure how tokens are distributed across a recipient's wallets.

<Steps>
  <Step title="Navigate to wallet distribution settings">
    Go to the recipient's wallet configuration.
  </Step>

  <Step title="Set distribution ratios">
    Assign a percentage or fixed amount to each wallet. Ratios must total 100%.
  </Step>

  <Step title="Save">
    The distribution configuration applies to all future vestings for that recipient.
  </Step>
</Steps>

<Tip>
  **API:** Use [Configure Wallet Distribution for Grant](/api/wallets/configure-wallet-distribution-for-grant) or [Set Token Wallet Distribution](/api/wallets/set-token-wallet-distribution) for programmatic configuration.
</Tip>

***

## Related

<CardGroup>
  <Card title="Wallet Verification API" icon="shield-check" href="/api/wallets/send-test-transaction">
    Automate wallet verification via API
  </Card>

  <Card title="Token Distributions" icon="share-nodes" href="/tga/client/token-distributions">
    Learn how distributions work after wallets are set up
  </Card>
</CardGroup>


# TGA FAQ
Source: https://docs.toku.com/tga/faq

Frequently asked questions about Token Grant Administration

## For Grant Recipients

<AccordionGroup>
  <Accordion title="How do I see my grants?">
    Log in to TGA and click **Grants** in the sidebar. You'll see all grants issued to you with their status, vesting progress, and claim history.
  </Accordion>

  <Accordion title="When can I claim my tokens?">
    You can claim tokens once they've vested. Check your grant details to see which tokens are vested and available to claim.
  </Accordion>

  <Accordion title="How do I set up my wallet?">
    Go to **Wallets** in the sidebar, click **Add Wallet**, and enter your wallet address. Make sure to use a self-custody wallet (like MetaMask, Coinbase Wallet, or Phantom) rather than an exchange address.
  </Accordion>

  <Accordion title="What is a cliff?">
    A cliff is a waiting period before any tokens vest. For example, with a 1-year cliff, no tokens vest during the first year. After the cliff, a portion (typically 25%) vests immediately.
  </Accordion>

  <Accordion title="What happens to my tokens if I leave the company?">
    Tokens that have already vested are yours to keep. Unvested tokens are typically forfeited, though specific terms vary by grant agreement.
  </Accordion>

  <Accordion title="How long does a claim take to process?">
    Most claims are processed within 24 hours. After approval, tokens are sent to your wallet. Actual delivery time depends on the blockchain network.
  </Accordion>

  <Accordion title="Why is my claim amount less than expected?">
    Your organization may withhold a portion of tokens for tax purposes. Check your claim details to see the gross amount, withholding, and net amount.
  </Accordion>

  <Accordion title="I don't see tokens in my wallet">
    Make sure you've added the token to your wallet. You may need to manually add the token using its contract address. Contact support if you need the token details.
  </Accordion>

  <Accordion title="What's the difference between vested and claimed?">
    **Vested** means you've earned the tokens but they're still in the system. **Claimed** means you've requested them and they've been (or are being) sent to your wallet.
  </Accordion>
</AccordionGroup>

***

## For Administrators

<AccordionGroup>
  <Accordion title="How do I create a grant?">
    Navigate to **Grants**, click **New Grant**, select the grant type, enter recipient details, configure the vesting schedule, and submit.
  </Accordion>

  <Accordion title="Can I modify a grant after it's created?">
    Grants can be modified before the recipient accepts. After acceptance, you'll need to cancel and create a new grant to change terms.
  </Accordion>

  <Accordion title="How do I process distributions?">
    Go to **Distributions** to see pending claims. Review each claim, verify the wallet address, and click **Approve** to process.
  </Accordion>

  <Accordion title="How do I set up custody integration?">
    Navigate to **Settings** > **Integrations**, select your custody provider, and follow the authentication steps. Contact support if you need help.
  </Accordion>

  <Accordion title="How do I cancel a grant?">
    Go to the grant details, click **Actions** > **Cancel Grant**. Note that vested tokens cannot be cancelled — only unvested portions can be forfeited.
  </Accordion>

  <Accordion title="How do I run reports?">
    Navigate to **Reports**, select the report type, set your date range and filters, then generate and export the report.
  </Accordion>

  <Accordion title="How do I bulk import grants?">
    Go to **Grants** > **Import**, download the CSV template, fill in the grant details, upload the file, and review before confirming.
  </Accordion>

  <Accordion title="What custody providers do you support?">
    TGA integrates with Fireblocks, Anchorage, Coinbase Prime, and Safe (Gnosis). Contact us if you need a different provider.
  </Accordion>
</AccordionGroup>

***

## General

<AccordionGroup>
  <Accordion title="Which blockchains are supported?">
    TGA supports Ethereum, Polygon, Solana, Arbitrum, Optimism, and other major networks. Specific support depends on your custody provider.
  </Accordion>

  <Accordion title="Is my data secure?">
    Yes. TGA uses enterprise-grade security including encryption, access controls, and audit logging. Tokens are held in institutional custody.
  </Accordion>

  <Accordion title="How do I get support?">
    Email [support@toku.com](mailto:support@toku.com) or visit our [contact page](https://www.toku.com/contact). Enterprise clients also have a dedicated account manager.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

<Card title="Contact Support" icon="headset" href="/getting-started/support">
  Get in touch with our team
</Card>


# Token Grant Administration
Source: https://docs.toku.com/tga/overview

Manage token grants, vesting schedules, and distributions

## What is TGA?

Token Grant Administration (TGA) is Toku's platform for managing token-based equity compensation. It covers the full lifecycle from grant creation through vesting to settlement.

***

## Core Capabilities

<CardGroup>
  <Card title="Grants" icon="award">
    Create and manage token grants with configurable vesting schedules
  </Card>

  <Card title="Distributions" icon="share-nodes">
    Process settlements through institutional custody providers
  </Card>

  <Card title="Wallets" icon="wallet">
    Manage recipient wallets with automated verification
  </Card>

  <Card title="Cap Table" icon="chart-pie">
    Track token ownership across your organization
  </Card>

  <Card title="Tax & Compliance" icon="shield-check">
    Tax calculation, withholding, and settlement documents
  </Card>

  <Card title="API" icon="code">
    Full REST API for programmatic integration
  </Card>
</CardGroup>

***

## Grant Types

| Type                               | Description                                        |
| ---------------------------------- | -------------------------------------------------- |
| **RTU** (Restricted Token Unit)    | Tokens subject to vesting and restrictions         |
| **RTA** (Restricted Token Award)   | Token awards with conditional restrictions         |
| **Token Bonus**                    | Performance-based token rewards                    |
| **TPA** (Token Purchase Agreement) | Agreements for token purchases                     |
| **Other**                          | Custom grant type name defined by the organization |

***

## How It Works

```mermaid theme={null}
flowchart LR
    A[Add Recipients] --> B[Create Grants]
    B --> C[Tokens Vest]
    C --> D[Tax Calculation]
    D --> E[Settlement]
    E --> F[Distribution to Wallets]
```

1. **Add recipients** — Onboard employees and assign roles
2. **Create grants** — Issue grants with vesting schedules
3. **Tokens vest** — Automatic vesting based on schedule
4. **Tax calculation** — Calculate and finalize tax obligations
5. **Settlement** — Execute distributions through custody providers
6. **Distribution** — Tokens delivered to recipient wallets

***

## For Administrators

<CardGroup>
  <Card title="Onboarding Checklist" icon="list-check" href="/tga/client/onboarding-checklist">
    Complete your 6-step account setup
  </Card>

  <Card title="Creating Grants" icon="plus" href="/tga/client/creating-grants">
    Issue token grants to recipients
  </Card>

  <Card title="Wallet Setup" icon="wallet" href="/tga/client/wallet-setup">
    Configure wallets and verification
  </Card>

  <Card title="Settlements" icon="file-invoice-dollar" href="/tga/client/settlements">
    Process token distributions
  </Card>
</CardGroup>

## For Recipients

<CardGroup>
  <Card title="Employee Portal" icon="user" href="/tga/user/employee-portal">
    Navigate the TGA portal
  </Card>

  <Card title="Understanding Vesting" icon="calendar" href="/tga/user/understanding-vesting">
    Learn how your tokens vest
  </Card>
</CardGroup>

## For Developers

<CardGroup>
  <Card title="API Reference" icon="code" href="/api/overview">
    65+ REST API endpoints with interactive playground
  </Card>

  <Card title="Quick Start" icon="rocket" href="/api/quickstart">
    Make your first API call in 5 minutes
  </Card>
</CardGroup>

***

## Ready to use Toku?

<div>
  <div>
    <h3>Bring token grants into one platform</h3>

    <p>
      Manage grants, vesting, wallets, settlements, and distributions with Toku.
    </p>
  </div>

  <a href="https://www.toku.com/get-started">
    Sign up for Toku
  </a>
</div>


# Employee Portal
Source: https://docs.toku.com/tga/user/employee-portal

Navigate the TGA portal as a grant recipient

## Overview

The TGA employee portal is where you view your token grants, track vesting progress, manage your wallet, and access tax documents.

***

## First Login

<Steps>
  <Step title="Check your email">
    You'll receive an invitation email from Toku with a link to set up your account.
  </Step>

  <Step title="Create your account">
    Click the link, set a secure password, and complete any required identity verification.
  </Step>

  <Step title="Set up MFA">
    If your organization requires multi-factor authentication, configure your authenticator app during first login.
  </Step>

  <Step title="Review your grants">
    After login, you'll see your dashboard with all token grants and vesting details.
  </Step>
</Steps>

***

## Dashboard

Your dashboard shows at a glance:

| Section              | What You See                               |
| -------------------- | ------------------------------------------ |
| **Token Grants**     | All grants issued to you with status       |
| **Vested Tokens**    | Tokens currently available                 |
| **Upcoming Vesting** | Next vesting dates and amounts             |
| **Wallet Status**    | Whether your wallet is set up and verified |

***

## Portal Sections

<CardGroup>
  <Card title="Your Grants" icon="award" href="/tga/user/viewing-your-grants">
    View grant details, amounts, and status
  </Card>

  <Card title="Vesting Schedule" icon="calendar" href="/tga/user/understanding-vesting">
    Track when your tokens vest
  </Card>

  <Card title="Wallet Setup" icon="wallet" href="/tga/user/wallet-setup">
    Add and verify your wallet address
  </Card>

  <Card title="Tax Documents" icon="file-lines" href="/tga/user/tax-documents">
    Access tax forms and settlement documents
  </Card>
</CardGroup>

***

## Key Actions

### Accept a Grant

When a new grant is issued to you, review the terms and click **Accept**. This starts the vesting clock.

### Set Up Your Wallet

Add your blockchain wallet address so you can receive token distributions. Your wallet must be verified through a test transaction before tokens can be sent.

### Track Vesting

Monitor your vesting progress with a visual timeline showing past and upcoming vesting events.

### Access Documents

View and download grant agreements, settlement confirmations, and tax documents.

***

## Notifications

You'll receive emails for:

* New grants issued to you
* Vesting events (tokens newly available)
* Wallet verification requests
* Settlement confirmations
* Document availability

***

## Security

* **Use a strong password** and enable MFA if available
* **Verify wallet addresses carefully** — tokens sent to wrong addresses cannot be recovered
* **Never share your private keys** or wallet seed phrase with anyone
* **Check the URL** — always ensure you're on the official Toku platform


# Tax Documents
Source: https://docs.toku.com/tga/user/tax-documents

Access tax-related documents for your token grants

## Overview

TGA provides tax-related documents to help you report token compensation on your tax returns. Access these documents in the **Documents** section of your portal.

***

## Available Documents

<CardGroup>
  <Card title="Distribution Statements" icon="file-lines">
    Records of tokens distributed to you
  </Card>

  <Card title="Vesting Reports" icon="calendar">
    Summary of tokens vested during the tax year
  </Card>

  <Card title="Exercise Records" icon="file-signature">
    For options: records of exercises
  </Card>

  <Card title="Tax Summaries" icon="file-invoice">
    Year-end summary for tax filing
  </Card>
</CardGroup>

***

## Accessing Documents

<Steps>
  <Step title="Navigate to Documents">
    Click **Documents** in the sidebar
  </Step>

  <Step title="Select document type">
    Choose the type of document you need
  </Step>

  <Step title="Select tax year">
    Pick the relevant tax year
  </Step>

  <Step title="Download">
    Click to download or view the document
  </Step>
</Steps>

***

## Document Details

### Distribution Statements

Shows each token distribution you received:

* Date of distribution
* Number of tokens
* Token value at distribution
* Any withholding applied

### Vesting Reports

Summary of vesting events:

* Vesting dates
* Tokens vested
* Fair market value at vesting

### Exercise Records (Options Only)

For option grants:

* Exercise date
* Number of options exercised
* Strike price paid
* Token value at exercise

***

## Tax Withholding

Your organization may withhold tokens for tax purposes:

* **Withheld amount** shown on distribution statements
* **Net tokens** are what you actually receive
* **Withholding records** available in your documents

***

## Important Dates

| Date                  | Relevance                                    |
| --------------------- | -------------------------------------------- |
| **Vesting date**      | When tokens vest — may trigger taxable event |
| **Distribution date** | When you receive tokens                      |
| **Exercise date**     | When you exercise options                    |
| **Year-end**          | Summary documents available in January       |

***

## Tax Considerations

<Warning>
  Token compensation may have significant tax implications. This documentation is for informational purposes only and does not constitute tax advice. Consult a qualified tax professional about your specific situation.
</Warning>

### General Guidance

* Token grants may be taxable at vesting or distribution
* The taxable value is typically the fair market value at the taxable event
* Options may have different tax treatment than RSUs
* Tax rules vary by jurisdiction

***

## Getting Help

For questions about:

* **Your documents** — Contact [support@toku.com](mailto:support@toku.com)
* **Tax filing** — Consult a tax professional
* **Withholding** — Contact your organization's HR or finance team

<Card title="TGA FAQ" icon="circle-question" href="/tga/faq">
  Common questions about token grants
</Card>

***

<Tip>
  **TGA User Guide** — Step 4 of 4. [Previous: Understanding Vesting](/tga/user/understanding-vesting)
</Tip>


# Understanding Vesting
Source: https://docs.toku.com/tga/user/understanding-vesting

How token vesting works and tracking your schedule

## What is Vesting?

Vesting is the process of earning your tokens over time. When you receive a grant, the tokens don't belong to you all at once — you earn them gradually according to a vesting schedule.

***

## How Vesting Works

### The Cliff

Most grants have a **cliff period** — an initial waiting period before any tokens vest. If you leave before the cliff, you typically forfeit all tokens.

### After the Cliff

Once the cliff passes, a chunk of tokens vest immediately. After that, tokens continue vesting on a regular schedule (usually monthly).

***

## Example: 10,000 Token Grant with 4-Year Vesting, 1-Year Cliff

| Timeline   | Event                        | Tokens Vested | Total  |
| ---------- | ---------------------------- | ------------- | ------ |
| Month 0    | Grant starts                 | 0             | 0      |
| Month 1–11 | Cliff period (nothing vests) | 0             | 0      |
| Month 12   | **Cliff!** 25% vests         | 2,500         | 2,500  |
| Month 13   | Monthly vest                 | \~208         | 2,708  |
| Month 14   | Monthly vest                 | \~208         | 2,917  |
| ...        | ...                          | ...           | ...    |
| Month 48   | **Fully vested**             | \~208         | 10,000 |

***

## Key Terms

| Term                  | Definition                                           |
| --------------------- | ---------------------------------------------------- |
| **Unvested**          | Tokens you haven't earned yet                        |
| **Vested**            | Tokens you've earned and can receive                 |
| **Cliff**             | Waiting period before any tokens vest                |
| **Vesting Frequency** | How often tokens vest (monthly, quarterly, annually) |
| **Fully Vested**      | All tokens in the grant have vested                  |

***

## Tracking Your Vesting

In the TGA portal:

1. Go to **Grants** and click on a grant
2. View the **Vesting Schedule** tab
3. See a timeline of past and upcoming vesting events
4. Check how many tokens are currently vested vs unvested

***

## What Happens When You Leave

| Scenario             | Result                                   |
| -------------------- | ---------------------------------------- |
| **Before cliff**     | All tokens forfeited                     |
| **After cliff**      | Keep vested tokens, forfeit unvested     |
| **Fully vested**     | Keep all tokens                          |
| **Terminated grant** | Vesting recalculated to termination date |

Your organization's admin handles the termination process. Check your grant agreement for specific terms regarding departure.

***

## Vesting Frequencies

| Frequency     | How It Works                             |
| ------------- | ---------------------------------------- |
| **Monthly**   | Tokens vest once per month (most common) |
| **Quarterly** | Tokens vest every 3 months               |
| **Annually**  | Tokens vest once per year                |

***

## Next Steps

<CardGroup>
  <Card title="Wallet Setup" icon="wallet" href="/tga/user/wallet-setup">
    Set up your wallet to receive vested tokens
  </Card>

  <Card title="Tax Documents" icon="file-lines" href="/tga/user/tax-documents">
    Understand tax implications
  </Card>
</CardGroup>


# Viewing Your Grants
Source: https://docs.toku.com/tga/user/viewing-your-grants

Understand and track your token grants

## Overview

The Grants page shows all token grants you've received from your organization. View grant details, track vesting progress, and see your total token compensation.

***

## Accessing Your Grants

1. Log in to TGA at [app.toku.com](https://app.toku.com)
2. Click **Grants** in the sidebar
3. View your list of grants

***

## Grant Information

Each grant displays:

| Field             | Description                    |
| ----------------- | ------------------------------ |
| **Grant Name**    | Descriptive name for the grant |
| **Grant Type**    | RTU, RTA, TPA, or Token Bonus  |
| **Total Amount**  | Total tokens in this grant     |
| **Vested**        | Tokens currently vested        |
| **Grant Date**    | When the grant was issued      |
| **Vesting Start** | When vesting begins            |
| **Status**        | Current grant status           |
| **Tags**          | Categorization labels          |

***

## Grant Detail View

Click any grant to see the full detail:

* **Vesting schedule** — Visual timeline with each tranche
* **Vesting progress** — Percentage complete with breakdown
* **Grant agreement** — Original terms and signed documents
* **Settlement history** — Past distributions from this grant

***

## Grant Statuses

| Status         | What It Means                                          |
| -------------- | ------------------------------------------------------ |
| **PENDING**    | Grant issued, waiting for you to accept                |
| **ACCEPTED**   | You've accepted the grant, tokens are actively vesting |
| **COMPLETED**  | All tokens have fully vested                           |
| **TERMINATED** | Grant was terminated (e.g., due to departure)          |
| **PAUSED**     | Vesting temporarily paused                             |

***

## Accepting a Grant

When you receive a new grant:

<Steps>
  <Step title="Review the terms">
    Read the grant name, token amount, vesting schedule, and any conditions.
  </Step>

  <Step title="Read the agreement">
    Review the full grant agreement document if one is attached.
  </Step>

  <Step title="Accept">
    Click **Accept Grant** to start the vesting clock.
  </Step>
</Steps>

<Warning>
  Review grant terms carefully before accepting. Once accepted, terms generally cannot be changed.
</Warning>

***

## Multiple Grants

If you have multiple grants (e.g., initial grant + refresh grant), each vests independently according to its own schedule. Your dashboard shows the combined totals.

***

## Next Steps

<CardGroup>
  <Card title="Understanding Vesting" icon="calendar" href="/tga/user/understanding-vesting">
    Learn how your tokens vest over time
  </Card>

  <Card title="Wallet Setup" icon="wallet" href="/tga/user/wallet-setup">
    Set up your wallet to receive tokens
  </Card>
</CardGroup>


# Setting Up Your Wallet
Source: https://docs.toku.com/tga/user/wallet-setup

Add and verify your blockchain wallet to receive token distributions

## Overview

Before you can receive token distributions, you need to add your blockchain wallet address to TGA and complete the verification process.

***

## Step 1: Add Your Wallet

<Steps>
  <Step title="Navigate to Wallet Settings">
    Click **Wallet Settings** in the sidebar, or look for the wallet setup prompt on your dashboard.
  </Step>

  <Step title="Enter your wallet address">
    Paste your blockchain wallet address. Make sure it's on a network supported by your organization (e.g., Ethereum, Solana, Polygon).
  </Step>

  <Step title="Select the network">
    Choose the blockchain network that matches your wallet. Your organization will have specific networks configured.
  </Step>

  <Step title="Submit">
    Click **Submit** to save your wallet. It will be in **Pending** status until verified.
  </Step>
</Steps>

<Warning>
  **Double-check your wallet address.** Tokens sent to an incorrect address cannot be recovered. Copy-paste the address directly from your wallet app — never type it manually.
</Warning>

***

## Step 2: Verify Your Wallet

Your organization uses test transactions to verify wallet ownership.

<Steps>
  <Step title="Receive test transaction">
    Your admin will send a small amount of tokens to your wallet. You'll get an email notification.
  </Step>

  <Step title="Check your wallet">
    Open your wallet app and confirm you received the test amount.
  </Step>

  <Step title="Confirm in TGA">
    Log back into TGA and confirm that you received the test transaction.
  </Step>

  <Step title="Wait for approval">
    Your admin reviews and approves the verified wallet. You'll receive a notification when approved.
  </Step>
</Steps>

***

## Wallet Statuses

| Status        | Meaning                                           |
| ------------- | ------------------------------------------------- |
| **Pending**   | Wallet submitted, awaiting test transaction       |
| **Test Sent** | Test transaction sent, awaiting your confirmation |
| **Verified**  | You confirmed receipt, awaiting admin approval    |
| **Approved**  | Wallet is active and ready for distributions      |
| **Archived**  | Wallet deactivated (replaced by a new one)        |

***

## Multiple Wallets

You may have multiple wallets if:

* You use different wallets for different networks
* Your organization supports multi-wallet distributions

If you have multiple active wallets, your admin configures how tokens are split across them (e.g., 70% to Wallet A, 30% to Wallet B).

***

## Changing Your Wallet

To update your wallet address:

1. Go to **Wallet Settings**
2. Add a new wallet with the updated address
3. The new wallet goes through verification
4. Once approved, your old wallet is automatically archived

<Tip>
  You cannot edit an existing wallet address. Add a new wallet instead, and the old one will be deactivated after the new one is approved.
</Tip>

***

## Wallet Security Tips

* **Use a self-custody wallet** — Hardware wallets (Ledger, Trezor) are recommended for large amounts
* **Back up your seed phrase** — Store it offline in a secure location
* **Never share private keys** — Toku will never ask for your private key
* **Verify the network** — Ensure your wallet supports the same network your organization uses

***

## Supported Wallet Types

Most standard wallets are supported, including:

* **MetaMask** — Ethereum, Polygon, Arbitrum, Base, Optimism
* **Phantom** — Solana
* **Ledger / Trezor** — Hardware wallets (via compatible interfaces)
* **Coinbase Wallet** — Multi-chain
* **Privy** — Embedded wallets (if enabled by your organization)

***

## Troubleshooting

| Issue                         | Solution                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| Test transaction not received | Check you're on the correct network; wait 10-15 minutes for confirmation               |
| Wrong network                 | Add a new wallet on the correct network                                                |
| Wallet rejected               | Contact your admin for the rejection reason                                            |
| Can't find wallet settings    | Check your sidebar — wallet setup may be under a different menu depending on your role |

***

## Next Steps

<CardGroup>
  <Card title="Understanding Vesting" icon="calendar" href="/tga/user/understanding-vesting">
    Learn when your tokens vest
  </Card>

  <Card title="Tax Documents" icon="file-lines" href="/tga/user/tax-documents">
    Access tax-related documents
  </Card>
</CardGroup>