v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB

Agent Operations

Create a transfer-in

Transfer funds from an external account to an internal account for the authenticated agent's customer. Accounts must belong to the agent's customer. Requires the CREATE_TRANSFERS permission in the agent's policy. If the agent's policy requires approval for this amount, the transaction will be created in a pending state and must be approved by the platform via POST /agents/{agentId}/actions/{actionId}/approve. This endpoint should only be used for external account sources with pull functionality (e.g. ACH Pull). Otherwise, use the payment instructions on the internal account to deposit funds.

post/agents/me/transfer-in

Headers

Idempotency-Keystring

Example:550e8400-e29b-41d4-a716-446655440000

A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.

Request body

amountinteger

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example request

{
  "source": {
    "accountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "destination": {
    "accountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
  },
  "amount": 12550
}

Response

Action submitted successfully. If the agent's policy requires approval, the returned AgentAction will have status PENDING_APPROVAL and no transaction yet. If the policy permits automatic execution, status will be APPROVED and transaction will be populated.

idstring required

System-generated unique identifier for this action.

agentIdstring required

The agent that submitted this action.

customerIdstring required

The customer on whose behalf the action was submitted.

platformCustomerIdstring required

Platform-specific ID of the customer.

status'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED' | 'FAILED' required

Status of an agent action.

Status	Description
PENDING_APPROVAL	Submitted by the agent, awaiting platform approval before execution
APPROVED	Approved by the platform; execution is in progress or completed
REJECTED	Rejected by the platform; the underlying transaction was not executed
FAILED	Approved but execution failed (e.g. quote expired, insufficient funds)

type'EXECUTE_QUOTE' | 'TRANSFER_OUT' | 'TRANSFER_IN' required

The type of action the agent is requesting.

Type	Description
EXECUTE_QUOTE	Execute a cross-currency quote
TRANSFER_OUT	Transfer from an internal account to an external account
TRANSFER_IN	Transfer from an external account to an internal account

rejectionReasonstring

Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.

createdAtstring date-time required

When the action was submitted by the agent.

updatedAtstring date-time required

When the action was last updated.

Example response

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "feesIncluded": 10,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    }
  },
  "transferDetails": {
    "amount": 50000,
    "currency": "USD",
    "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "destinationAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "destination": {
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
    },
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "fees": 10,
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF",
      "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
    },
    "rateDetails": {
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    }
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z"
}