> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Allocate to a Bonded Earn strategy > Submits a request to allocate funds from the specified account into the bonded earn strategy identified in the path. The request is processed asynchronously. A successful response only confirms that the request was accepted and returns its `request_id`; poll the request status endpoint with that identifier to learn whether the allocation succeeded or failed. Reuse the same `Idempotency-Key` only when retrying the same request. Keys are scoped to the account. Retrying with the same key, strategy, and `amount` returns the original `request_id` without allocating again. Reusing the key with a different strategy or `amount`, or for a deallocation instead of an allocation, returns a conflict error. Rejected requests return a machine-readable `error.code`; branch on it rather than on the message text. Known codes are `strategy_not_found`, `amount_too_high`, `idempotency_key_reused`, and `allocation_in_progress`. An amount below the strategy's minimum allocation (`user_min_allocation` in the strategy list) returns a generic `bad_request`. An account that is not eligible for the strategy returns `forbidden`. A 403 with the code `gateway` is an authorization failure from the API gateway instead, so branch on `error.code` to tell the two apart. The account balance and the strategy cap are checked after the request is accepted. If the request fails then, the request status endpoint reports it in `error.reason`, as `insufficient_balance`, `above_user_cap`, or `not_eligible`. A request that failed after it was accepted keeps its `Idempotency-Key`, so retry with a new key. New codes may be added, so treat an unknown code as a generic `bad_request`, `not_found`, or `request_conflict` error. ## OpenAPI ````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/allocate openapi: 3.1.0 info: title: PWS Public API version: '1' description: >- Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications. contact: name: Payward Services servers: - url: https://api.sandbox.services.payward.com security: [] tags: - name: Assets description: List the assets PWS is willing to swap. x-displayName: Assets - name: Conversions description: >- Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits. x-displayName: Conversions - name: Auto Earn description: >- Manage Auto Earn preferences and retrieve allocation and reward information. x-displayName: Auto Earn - name: Bonded Earn description: >- Allocate funds to and deallocate funds from bonded earn strategies, review allocations, and track request status. x-displayName: Bonded Earn - name: Funding description: >- Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts. x-displayName: Funding - name: Derivative transfers description: >- Move funds between an account's spot balance and the same owner's futures balance. x-displayName: Derivative transfers - name: Portfolio description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' x-displayName: Portfolio - name: Ramp description: >- Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences. x-displayName: Ramp - name: Reports description: Settlement and reconciliation reports for the partner. x-displayName: Reports - name: Swaps description: Account-funded quotes that lock a price until they expire or are executed. x-displayName: Swaps - name: Onchain quotes description: Wallet-funded quotes that return the data needed to settle onchain. x-displayName: Onchain quotes - name: Price trigger swaps description: Swaps that wait for a target price before submitting a trade. x-displayName: Price trigger swaps - name: Travel Rule verifications description: Travel Rule address ownership verification flows. x-displayName: Travel Rule verifications - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions an account-owned user from an external reference and optional email. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. x-displayName: Users - name: Verifications description: Identity verification (KYC) submission and status for end users. x-displayName: Verifications - name: Webhooks description: >- Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures. x-displayName: Webhooks paths: /v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/allocate: post: tags: - Bonded Earn summary: Allocate to a Bonded Earn strategy description: >- Submits a request to allocate funds from the specified account into the bonded earn strategy identified in the path. The request is processed asynchronously. A successful response only confirms that the request was accepted and returns its `request_id`; poll the request status endpoint with that identifier to learn whether the allocation succeeded or failed. Reuse the same `Idempotency-Key` only when retrying the same request. Keys are scoped to the account. Retrying with the same key, strategy, and `amount` returns the original `request_id` without allocating again. Reusing the key with a different strategy or `amount`, or for a deallocation instead of an allocation, returns a conflict error. Rejected requests return a machine-readable `error.code`; branch on it rather than on the message text. Known codes are `strategy_not_found`, `amount_too_high`, `idempotency_key_reused`, and `allocation_in_progress`. An amount below the strategy's minimum allocation (`user_min_allocation` in the strategy list) returns a generic `bad_request`. An account that is not eligible for the strategy returns `forbidden`. A 403 with the code `gateway` is an authorization failure from the API gateway instead, so branch on `error.code` to tell the two apart. The account balance and the strategy cap are checked after the request is accepted. If the request fails then, the request status endpoint reports it in `error.reason`, as `insufficient_balance`, `above_user_cap`, or `not_eligible`. A request that failed after it was accepted keeps its `Idempotency-Key`, so retry with a new key. New codes may be added, so treat an unknown code as a generic `bad_request`, `not_found`, or `request_conflict` error. operationId: allocateBondedEarn parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/BondedEarn_BondedStrategyId' - $ref: '#/components/parameters/RequiredIdempotencyKey' requestBody: required: true content: application/json: schema: description: Request to allocate funds into a bonded earn strategy. type: object additionalProperties: false required: - amount properties: amount: $ref: '#/components/schemas/BondedEarn_BondedAmount' examples: allocate: summary: Allocate 2 units of the strategy's asset value: amount: '2.0' responses: '202': description: The allocation request was accepted and is pending. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BondedEarn_BondedRequestAccepted' required: - data examples: accepted: summary: Allocation request accepted value: data: request_id: EBARERNY-PXH3CV-XQJL2O '400': $ref: '#/components/responses/BondedEarnAllocateBadRequestResponse' '401': $ref: '#/components/responses/EarnUnauthenticatedResponse' '403': $ref: '#/components/responses/BondedEarnWriteForbiddenResponse' '404': $ref: '#/components/responses/BondedEarnWriteNotFoundResponse' '409': $ref: '#/components/responses/BondedEarnConflictResponse' '429': $ref: '#/components/responses/EarnResourceExhaustedResponse' '500': $ref: '#/components/responses/EarnInternalResponse' '503': $ref: '#/components/responses/EarnUnavailableResponse' '504': $ref: '#/components/responses/EarnDeadlineExceededResponse' security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: parameters: AccountId: name: account_id in: path required: true example: WVSD33HRMGSZUBM7 schema: $ref: '#/components/schemas/AccountId' BondedEarn_BondedStrategyId: name: strategy_id in: path description: >- Identifier of the bonded earn strategy to allocate to or deallocate from. required: true example: ESQEFMZ-JPPIY-3KXFJ2 schema: $ref: '#/components/schemas/BondedEarn_BondedStrategyId' RequiredIdempotencyKey: name: Idempotency-Key in: header required: true schema: $ref: '#/components/schemas/IdempotencyKey' example: 550e8400-e29b-41d4-a716-446655440000 schemas: BondedEarn_BondedAmount: description: Amount in the strategy's asset, as a decimal string. type: string minLength: 1 maxLength: 64 example: '2.0' BondedEarn_BondedRequestAccepted: description: Confirmation that an allocate or deallocate request was accepted. type: object additionalProperties: false required: - request_id properties: request_id: description: >- Identifier of the submitted request. Use it to look up the request status. type: string minLength: 1 maxLength: 64 AccountId: description: Globally unique public identifier for an account. type: string minLength: 14 maxLength: 42 BondedEarn_BondedStrategyId: description: Identifier of the bonded earn strategy. type: string minLength: 20 maxLength: 20 pattern: ^ES[A-Z2-7]{5}-[A-Z2-7]{5}-[A-Z2-7]{6}$ example: ESQEFMZ-JPPIY-3KXFJ2 IdempotencyKey: description: >- Client-generated canonical UUIDv4 that uniquely identifies a request for safe retries. type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 550e8400-e29b-41d4-a716-446655440000 BadRequestError: title: Bad Request description: Request validation failed or the request could not be processed. oneOf: - title: Bad Request allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 const: 400 code: type: string enum: - bad_request - title: Gateway description: >- Gateway-level validation failure returned before the request reaches the service. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 400 code: type: string const: gateway BondedEarn_AmountTooHighError: description: The requested `amount` is larger than the system can represent. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 400 code: type: string enum: - amount_too_high UnauthenticatedError: title: Unauthenticated description: Authentication credentials are missing, invalid, or not accepted. oneOf: - title: Unauthenticated allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 401 code: type: string enum: - unauthenticated - title: Gateway description: Authentication failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 401 code: type: string const: gateway ForbiddenError: title: Forbidden description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 403 code: type: string enum: - forbidden - title: Gateway description: Authorization failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway NotFoundError: description: The requested resource was not found. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 404 code: type: string enum: - not_found BondedEarn_StrategyNotFoundError: description: The strategy identified in the path does not exist. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 404 code: type: string enum: - strategy_not_found BondedEarn_RequestConflictError: description: >- The request conflicts with a request that was already recorded or is still running, for example because the idempotency key was already used for a different strategy or amount. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 409 code: type: string enum: - request_conflict BondedEarn_IdempotencyKeyReusedError: description: >- The `Idempotency-Key` was already used for a request with a different strategy, `amount`, or direction. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 409 code: type: string enum: - idempotency_key_reused BondedEarn_AllocationInProgressError: description: >- Another allocation change is already in progress, so this request cannot be accepted yet. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 409 code: type: string enum: - allocation_in_progress ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 500 code: type: string enum: - internal UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 503 code: type: string enum: - unavailable DeadlineExceededError: description: The request deadline was exceeded before a response could be produced. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 504 code: type: string enum: - deadline_exceeded PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: Enforces HTTPS for the duration specified by `max-age`. schema: type: string example: max-age=31536000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store responses: BondedEarnAllocateBadRequestResponse: description: The request was rejected. Branch on `error.code`. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: oneOf: - $ref: '#/components/schemas/BadRequestError' title: Bad request - $ref: '#/components/schemas/BondedEarn_AmountTooHighError' title: Amount too high examples: invalid-request: $ref: '#/components/examples/earn-bad-request' amount-too-high: $ref: '#/components/examples/bonded-earn-amount-too-high' EarnUnauthenticatedResponse: description: Authentication failed headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: $ref: '#/components/examples/earn-unauthenticated' BondedEarnWriteForbiddenResponse: description: >- The account is not eligible for the strategy (`forbidden`), or the API gateway rejected the request (`gateway`). Branch on `error.code`. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: not-eligible: $ref: '#/components/examples/earn-forbidden' BondedEarnWriteNotFoundResponse: description: The strategy does not exist. Branch on `error.code`. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: oneOf: - $ref: '#/components/schemas/NotFoundError' title: Not found - $ref: '#/components/schemas/BondedEarn_StrategyNotFoundError' title: Strategy not found examples: strategy-not-found: $ref: '#/components/examples/bonded-earn-strategy-not-found' BondedEarnConflictResponse: description: >- The request conflicts with a request that was already recorded or is still running. Branch on `error.code`. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: oneOf: - $ref: '#/components/schemas/BondedEarn_RequestConflictError' title: Request conflict - $ref: '#/components/schemas/BondedEarn_IdempotencyKeyReusedError' title: Idempotency key reused - $ref: '#/components/schemas/BondedEarn_AllocationInProgressError' title: Allocation in progress examples: idempotency-key-reused: $ref: '#/components/examples/bonded-earn-idempotency-key-reused' allocation-in-progress: $ref: '#/components/examples/bonded-earn-allocation-in-progress' request-conflict: $ref: '#/components/examples/bonded-earn-request-conflict' EarnResourceExhaustedResponse: description: Rate limit exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: $ref: '#/components/examples/earn-resource-exhausted' EarnInternalResponse: description: Internal server error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: $ref: '#/components/examples/earn-internal' EarnUnavailableResponse: description: Service unavailable headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: $ref: '#/components/examples/earn-service-unavailable' EarnDeadlineExceededResponse: description: Deadline exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: $ref: '#/components/examples/earn-deadline-exceeded' examples: earn-bad-request: summary: Invalid request value: error: type: earn_error instance: req_01H00000000000000000000000 status: 400 code: bad_request causes: - field: account_id message: must be a valid account identifier bonded-earn-amount-too-high: summary: Amount too large to represent value: error: type: earn_error instance: req_01H00000000000000000000000 status: 400 code: amount_too_high causes: - field: amount message: The amount is outside the range that can be processed earn-unauthenticated: summary: Authentication failed value: error: type: earn_error instance: req_01H00000000000000000000000 status: 401 code: unauthenticated earn-forbidden: summary: Caller is not allowed value: error: type: earn_error instance: req_01H00000000000000000000000 status: 403 code: forbidden bonded-earn-strategy-not-found: summary: Strategy not found value: error: type: earn_error instance: req_01H00000000000000000000000 status: 404 code: strategy_not_found bonded-earn-idempotency-key-reused: summary: Idempotency key reused for a different request value: error: type: earn_error instance: req_01H00000000000000000000000 status: 409 code: idempotency_key_reused causes: - field: idempotency_key message: Idempotency key already used for a different request bonded-earn-allocation-in-progress: summary: Another request is running on the strategy value: error: type: earn_error instance: req_01H00000000000000000000000 status: 409 code: allocation_in_progress causes: - field: request message: Another allocation is already running on this strategy bonded-earn-request-conflict: summary: Request conflicts with an existing request value: error: type: earn_error instance: req_01H00000000000000000000000 status: 409 code: request_conflict earn-resource-exhausted: summary: Rate limit exceeded value: error: type: earn_error instance: req_01H00000000000000000000000 status: 429 code: resource_exhausted earn-internal: summary: Internal error value: error: type: earn_error instance: req_01H00000000000000000000000 status: 500 code: internal earn-service-unavailable: summary: Service unavailable value: error: type: earn_error instance: req_01H00000000000000000000000 status: 503 code: unavailable earn-deadline-exceeded: summary: Request deadline exceeded value: error: type: earn_error instance: req_01H00000000000000000000000 status: 504 code: deadline_exceeded securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey in: header name: API-Sign description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey in: header name: API-Nonce description: Monotonically increasing nonce included in the request signature. ````