> ## Documentation Index > Fetch the complete documentation index at: https://docs.mls.onchainden.com/llms.txt > Use this file to discover all available pages before exploring further. # Propose adding policies > [Admin Only] Creates a proposal to add new policies to the organization. Only admin API members can make requests to this endpoint. ## OpenAPI ````yaml /openapi.yaml post /policies/proposals/add openapi: 3.1.0 info: title: Den API version: 2.0.0 description: > API for managing wallets with Den. This API provides programmatic access to all platform capabilities including wallet accounts, members, groups, policies, and transactions. ## Authentication All API requests require authentication via Bearer token in the Authorization header. ## Idempotency All mutation requests (POST, PUT, DELETE) require an X-Idempotency-Key header for safe retries. ## Two Transaction Types - **Account Transactions**: Value movement and contract interactions (governed by policies) - **Organization Operations**: Governance/admin changes (governed by admin threshold) servers: - url: https://api.onchainden.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Members description: Manage organization members - name: Groups description: Manage member groups - name: Policies description: Manage transaction policies - name: Accounts description: Manage wallet accounts - name: Transactions description: Create and execute account transactions - name: Admins description: Manage admin configuration - name: AuditLogs description: View audit log entries paths: /policies/proposals/add: post: tags: - Policies summary: Propose adding policies description: >- [Admin Only] Creates a proposal to add new policies to the organization. Only admin API members can make requests to this endpoint. operationId: createPolicyAddProposal parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - policies properties: policies: type: array items: allOf: - $ref: '#/components/schemas/PolicyInput' - type: object properties: id: not: {} description: List of new policies to add (must not include id) example: policies: - name: Small USDC Transfers type: AUTO_APPROVAL transactionType: TOKEN_TRANSFER networkId: 1 accountIds: - acc_1 initiatorSetting: null approverSetting: null limitation: null tokenTransferCondition: tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amountThreshold: '1000000000' destinationAddresses: [] responses: '200': description: Policy add proposal created content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OrganizationOperationPoliciesAdd' example: data: id: prop_pol_add_123 resourceType: policies action: create signatureStatus: approvalReady executionStatus: completed threshold: 2 approvals: [] rejections: [] createdAt: '2026-01-18T00:00:00.000Z' expiresAt: '2026-01-25T00:00:00.000Z' data: policies: - name: Small USDC Transfers type: AUTO_APPROVAL transactionType: TOKEN_TRANSFER networkId: 1 accountIds: - acc_1 initiatorSetting: null approverSetting: null limitation: null tokenTransferCondition: tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amountThreshold: '1000000000' destinationAddresses: [] result: resolution: approved resources: - type: policy id: pol_new1 uri: /api/v1/policies/pol_new1 examples: success: value: data: id: prop_pol_add_123 resourceType: policies action: create signatureStatus: approvalReady executionStatus: completed threshold: 2 approvals: [] rejections: [] createdAt: '2026-01-18T00:00:00.000Z' expiresAt: '2026-01-25T00:00:00.000Z' data: policies: - name: Small USDC Transfers type: AUTO_APPROVAL transactionType: TOKEN_TRANSFER networkId: 1 accountIds: - acc_1 initiatorSetting: null approverSetting: null limitation: null tokenTransferCondition: tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amountThreshold: '1000000000' destinationAddresses: [] result: resolution: approved resources: - type: policy id: pol_new1 uri: /api/v1/policies/pol_new1 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '426': $ref: '#/components/responses/UpgradeRequired' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: javascript label: SDK source: | const client = new DenClient({ apiKey: 'ck_live_...' }); const proposal = await client.createUpdatePoliciesProposal({ changes: [ { action: 'add', data: { name: 'Small USDC Transfers', type: 'AUTO_APPROVAL', transactionType: 'TOKEN_TRANSFER', networkId: 1, accountIds: ['acc_1'], initiatorSetting: null, approverSetting: null, limitation: null, tokenTransferCondition: { tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', amountThreshold: '1000000000', destinationAddresses: [], }, }, }, ], }); components: parameters: IdempotencyKey: name: X-Idempotency-Key in: header required: true schema: type: string format: uuid description: Idempotency key for safely retrying mutation requests. schemas: PolicyInput: oneOf: - allOf: - $ref: '#/components/schemas/TokenTransferPolicyInput' title: Token Transfer - allOf: - $ref: '#/components/schemas/ContractInteractionPolicyInput' title: Contract Interaction - allOf: - $ref: '#/components/schemas/AnyTransactionPolicyInput' title: Any Transaction OrganizationOperationPoliciesAdd: allOf: - $ref: '#/components/schemas/OrganizationOperationBase' - type: object properties: resourceType: type: string const: policies action: type: string const: create data: $ref: '#/components/schemas/PolicyAddProposalData' example: id: prop_pol_add_123 resourceType: policies action: create signatureStatus: approvalReady executionStatus: completed threshold: 2 approvals: [] rejections: [] createdAt: '2026-01-18T00:00:00.000Z' expiresAt: '2026-01-25T00:00:00.000Z' data: policies: - name: Small USDC Transfers type: AUTO_APPROVAL transactionType: TOKEN_TRANSFER networkId: 1 accountIds: - acc_1 initiatorSetting: null approverSetting: null limitation: null tokenTransferCondition: tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' amountThreshold: '1000000000' destinationAddresses: [] result: resolution: approved resources: - type: policy id: pol_new1 uri: /api/v1/policies/pol_new1 TokenTransferPolicyInput: allOf: - $ref: '#/components/schemas/PolicyInputBase' - type: object properties: transactionType: type: string const: TOKEN_TRANSFER tokenTransferCondition: $ref: '#/components/schemas/PolicyTokenTransferCondition' ContractInteractionPolicyInput: allOf: - $ref: '#/components/schemas/PolicyInputBase' - type: object properties: transactionType: type: string const: CONTRACT_INTERACTION contractInteractionCondition: $ref: '#/components/schemas/PolicyContractInteractionCondition' AnyTransactionPolicyInput: allOf: - $ref: '#/components/schemas/PolicyInputBase' - type: object properties: transactionType: type: string const: ANY OrganizationOperationBase: type: object required: - id - resourceType - action - signatureStatus - executionStatus - threshold - approvals - rejections - createdAt - expiresAt - data properties: id: type: string example: prop_abc resourceType: $ref: '#/components/schemas/ResourceType' action: $ref: '#/components/schemas/ProposalAction' signatureStatus: $ref: '#/components/schemas/SignatureStatus' executionStatus: $ref: '#/components/schemas/ExecutionStatus' threshold: type: integer example: 2 approvals: type: array items: $ref: '#/components/schemas/MemberSummary' rejections: type: array items: $ref: '#/components/schemas/MemberSummary' createdAt: type: string format: date-time expiresAt: type: string format: date-time data: description: Proposed resource state after execution. signingPayloads: $ref: '#/components/schemas/ReviewSigningPayloads' description: >- Present only while signatures can still be collected for non-expired organization operations result: $ref: '#/components/schemas/OrganizationOperationResult' description: Present only after execution PolicyAddProposalData: type: object required: - policies properties: policies: type: array items: $ref: '#/components/schemas/PolicyInput' description: New policies to add Error: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' PolicyInputBase: type: object required: - name - type - transactionType - networkId - accountIds properties: id: type: string description: >- Include to preserve/update an existing policy. Omit for new policies. name: type: string description: type: string nullable: true type: $ref: '#/components/schemas/PolicyType' transactionType: $ref: '#/components/schemas/PolicyTransactionType' networkId: $ref: '#/components/schemas/NetworkId' accountIds: type: array items: type: string nullable: true description: >- Account IDs this policy applies to. null = policy applies to all accounts limitation: $ref: '#/components/schemas/PolicyLimitation' nullable: true initiatorSetting: $ref: '#/components/schemas/PolicyInitiatorSettingInput' approverSetting: $ref: '#/components/schemas/PolicyApproverSettingInput' PolicyTokenTransferCondition: type: object nullable: true description: >- Token transfer condition with enriched token details - null values mean "any" (no restriction) properties: tokenAddress: type: string nullable: true description: Contract address of token, null = native token or any token pattern: ^0x[a-fA-F0-9]{40}$ example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' tokenSymbol: type: string readOnly: true description: >- Token symbol (e.g., "USDC", "ETH"), enriched from token metadata. Response-only field. example: USDC tokenName: type: string nullable: true readOnly: true description: >- Full token name (e.g., "USD Coin"), enriched from token metadata. Response-only field. example: USD Coin tokenLogoUrl: type: string nullable: true readOnly: true description: URL to token logo image. Response-only field. example: https://assets.onchainden.com/tokens/usdc.png tokenDecimals: type: integer readOnly: true description: Token decimals (e.g., 6 for USDC, 18 for ETH). Response-only field. example: 6 amountThreshold: type: string nullable: true description: Max amount in token's smallest unit (wei), null = any amount example: '1000000000' destinationAddresses: type: array items: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Allowed destinations, [] = any destination example: [] example: tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' tokenSymbol: USDC tokenName: USD Coin tokenLogoUrl: https://assets.onchainden.com/tokens/usdc.png tokenDecimals: 6 amountThreshold: '1000000000' destinationAddresses: [] PolicyContractInteractionCondition: type: array nullable: true items: $ref: '#/components/schemas/PolicyContractCondition' description: >- Contract interaction conditions. Empty array = any contract/function allowed ResourceType: type: string enum: - members - groups - policies - accounts - admins ProposalAction: type: string enum: - create - update - remove - delete SignatureStatus: type: string enum: - pendingInitiatorSignature - pendingReviewSignatures - approvalReady - rejectionReady - approvalAndRejectionReady - expired description: > Current signature state in the approval workflow: - pendingInitiatorSignature: Account Transactions only - awaiting initiator signature - pendingReviewSignatures: Neither approval nor rejection threshold met - approvalReady: Approval threshold met, rejection not met - rejectionReady: Rejection threshold met, approval not met - approvalAndRejectionReady: Both thresholds met, either can be executed - expired: Proposal expired before execution ExecutionStatus: type: string nullable: true enum: - null - processing - completed - rejected - failed - blocked description: | Execution lifecycle state: - null: Not yet attempted - processing: Execution in progress - completed: Successfully executed - rejected: Successfully rejected - failed: Execution failed - blocked: Blocked by policy or constraint MemberSummary: type: object description: Abbreviated member info used in approvals/rejections arrays required: - id - name - type - walletAddress properties: id: type: string example: mem_123 name: type: string example: Alice type: $ref: '#/components/schemas/MemberType' walletAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ ReviewSigningPayloads: type: object required: - approvePayload - rejectPayload properties: approvePayload: type: string description: Payload for approval signature rejectPayload: type: string description: Payload for rejection signature OrganizationOperationResult: type: object required: - resolution properties: resolution: type: string enum: - approved - rejected description: Final outcome of the proposal execution resources: type: array items: $ref: '#/components/schemas/OrganizationOperationResultResource' description: Resources created or modified. Empty when rejected. ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable error message details: $ref: '#/components/schemas/ErrorDetails' PolicyType: type: string enum: - AUTO_APPROVAL - MANUAL_APPROVAL description: | - AUTO_APPROVAL: Executes after initiator signature - MANUAL_APPROVAL: Requires approver votes PolicyTransactionType: type: string enum: - TOKEN_TRANSFER - CONTRACT_INTERACTION - ANY NetworkId: type: integer example: 1 description: Network chain ID PolicyLimitation: type: object required: - hours - initiatorScope - sourceAccountScope - destinationScope properties: hours: type: integer description: Rolling time window in hours example: 24 initiatorScope: $ref: '#/components/schemas/PolicyLimitationScope' sourceAccountScope: $ref: '#/components/schemas/PolicyLimitationScope' destinationScope: $ref: '#/components/schemas/PolicyLimitationScope' PolicyInitiatorSettingInput: oneOf: - allOf: - $ref: '#/components/schemas/PolicyInitiatorSettingInputUser' title: User - allOf: - $ref: '#/components/schemas/PolicyInitiatorSettingInputGroup' title: Group nullable: true description: Who can initiate transactions. null = any organization member PolicyApproverSettingInput: oneOf: - allOf: - $ref: '#/components/schemas/PolicyApproverSettingInputUser' title: User - allOf: - $ref: '#/components/schemas/PolicyApproverSettingInputGroup' title: Group nullable: true description: >- Who can approve transactions. null = any organization member (for MANUAL_APPROVAL) PolicyContractCondition: type: object required: - contractAddress - allowedFunctions properties: contractAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' allowedFunctions: type: array items: $ref: '#/components/schemas/PolicyFunction' description: >- Allowed functions on this contract. Empty array = any function allowed example: - name: swapExactTokensForTokens selector: '0x38ed1739' - name: swapTokensForExactTokens selector: '0x8803dbee' MemberType: type: string enum: - user - api description: Type of member (user for human members, api for bots) OrganizationOperationResultResource: type: object required: - type - id properties: type: type: string description: Resource type that was created, updated, or removed example: member id: type: string description: Unique identifier of the affected resource example: mem_new1 uri: type: string description: >- Canonical URI for the affected resource (omitted for removals/deletes) example: /api/v1/members/mem_new1 ErrorCode: type: string enum: - validationError - invalidSignature - unauthorized - forbidden - notFound - conflict - thresholdNotMet - proposalExpired - idempotencyConflict - upgradeRequired - rateLimited - internalError description: Machine-readable error codes ErrorDetails: type: object additionalProperties: true description: Additional error details (structure varies by error type) properties: field: type: string description: Field that caused the error (for validation errors) message: type: string description: Detailed message about the error PolicyLimitationScope: type: string enum: - PER_ITEM - ALL_ITEMS description: | - PER_ITEM: Per user/account/destination - ALL_ITEMS: All users/accounts/destinations share cap PolicyInitiatorSettingInputUser: type: object required: - type - userId properties: type: type: string const: user userId: type: string description: User ID of the initiator example: user_123 PolicyInitiatorSettingInputGroup: type: object required: - type - groupId properties: type: type: string const: group groupId: type: string description: Group ID example: group_123 PolicyApproverSettingInputUser: type: object required: - type - userId properties: type: type: string const: user userId: type: string description: User ID of the approver example: user_123 PolicyApproverSettingInputGroup: type: object required: - type - groupId - threshold properties: type: type: string const: group groupId: type: string description: Group ID example: group_123 threshold: type: integer description: Number of votes required from group members example: 2 PolicyFunction: type: object required: - name - selector description: A contract function with its 4-byte selector properties: name: type: string description: Function name example: transfer selector: type: string description: 4-byte function selector pattern: ^0x[a-fA-F0-9]{8}$ example: '0xa9059cbb' responses: ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: validationError message: Validation failed details: field: name message: Name is required Unauthorized: description: API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Invalid API key Forbidden: description: Not permitted for this action content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: Not permitted for this action Conflict: description: Resource already exists or proposal already queued content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conflict message: Resource already exists UnprocessableEntity: description: >- Request cannot be processed due to proposal state or idempotency conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: thresholdNotMet: value: error: code: thresholdNotMet message: Threshold not reached proposalExpired: value: error: code: proposalExpired message: Proposal expired idempotencyConflict: value: error: code: idempotencyConflict message: Idempotency key used with different request body UpgradeRequired: description: HTTPS required; plain HTTP requests are rejected content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: upgradeRequired message: HTTPS required RateLimited: description: Too many requests content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rateLimited message: Too many requests InternalError: description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internalError message: Server error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API key authentication. Include your API key in the Authorization header. ````