Wallet REST

Liste as wallets do cliente autenticado, consulte as transações de cada uma e mova fundos entre wallets e contas de plataformas de negociação. Os endpoints de taxa de câmbio e de transferência estão em versão beta e podem ser alterados sem aviso prévio.

Visão Geral

As APIs de Wallet permitem que uma aplicação leia as wallets do cliente autenticado e o respetivo histórico de transações, e mova fundos entre elas. Liste todas as wallets com os seus saldos através do endpoint wallets, percorra os movimentos de uma única wallet através do endpoint transactions e mova fundos com os endpoints transfers. Todos os endpoints são chamadas REST padrão e requerem o âmbito OAuth2 payment.

REST API

Estas são APIs REST padrão que utilizam métodos HTTP (GET, POST). Todos os pedidos requerem o cabeçalho Deriv-App-ID: YOUR_APP_ID e um token Authorization: Bearer YOUR_OAUTH_TOKEN com o âmbito payment.

Especificação OpenAPI

Consulte a especificação OpenAPI completa para definições de esquema detalhadas e exemplos:

OpenAPI Spec →

Fluxo de Trabalho Típico

Liste as wallets do cliente com GET /wallet/v1/wallets. Cada entrada apresenta os seus saldos na moeda nativa da wallet; forneça conversion_currency para receber também um total convertido.
Obtenha os movimentos de uma wallet com GET /wallet/v1/transactions/{wallet_type}. Os resultados são paginados por cursor; siga links.next e links.prev para os percorrer.
Para uma transferência entre moedas diferentes, consulte primeiro a taxa com GET /wallet/v1/exchange-rate. Envie o exchange_rate e o rate_token que são devolvidos quando executar.
Pré-visualize a transferência com POST /wallet/v1/transfers/validate. Não movimenta qualquer valor e devolve a taxa, o montante líquido a sair da conta de origem e o montante estimado que o destino recebe.
Execute-o com POST /wallet/v1/transfers entre wallets na mesma moeda, POST /wallet/v1/transfers/exchange entre wallets em moedas diferentes, ou POST /wallet/v1/transfers/platforms entre uma wallet e uma conta de plataforma de negociação. Cada um utiliza um request_id como chave de idempotência.

Endpoints Disponíveis

Lista de WalletsGet

Devolve as wallets pertencentes ao cliente autenticado, com cada saldo apresentado na moeda nativa da wallet. Forneça um conversion_currency para receber também cada saldo convertido nessa moeda e utilize start_date_time e end_date_time para delimitar a janela do saldo./wallet/v1/wallets

Transações de WalletGet

Devolve uma lista paginada por cursor das transações de uma das wallets do cliente autenticado, identificada por wallet_type. Filtre por request_id, transaction_currency e um intervalo de datas. Cada linha apresenta um channel que mostra como o dinheiro se movimentou e uma category calculada em relação a quem faz a chamada./wallet/v1/transactions/{wallet_type}

Taxa de CâmbioGetBeta

Devolve uma cotação para conversão entre duas moedas. A cotação inclui a taxa de câmbio e um rate_token — passe ambos para uma transferência entre moedas para executar à taxa cotada./wallet/v1/exchange-rate

Validar TransferênciaPostBeta

Verifica uma transferência em relação às regras de transferência antes de a executar e devolve a taxa, o montante líquido que sai da conta de origem e o montante estimado que o destino recebe. A validação não move qualquer valor. Uma transferência inválida devolve um erro a descrever o que falhou, pelo que is_valid é sempre verdadeiro em caso de sucesso./wallet/v1/transfers/validate

Transferência entre WalletsPostBeta

Move fundos entre duas wallets pertencentes ao cliente autenticado, na mesma moeda. Qualquer taxa aplicável é deduzida do montante antes da execução, pelo que deve validar a transferência primeiro para pré-visualizar a taxa e o montante líquido. request_id é a chave de idempotência: reenviar uma que já tenha utilizado não cria uma transferência duplicada./wallet/v1/transfers

Transferência entre MoedasPostBeta

Move fundos entre duas wallets pertencentes ao cliente autenticado que detêm moedas diferentes. Consulte primeiro a taxa com o endpoint exchange-rate e, em seguida, envie o exchange_rate e o rate_token devolvidos para executar a essa taxa. Qualquer taxa de câmbio de moeda aplicável é deduzida do montante./wallet/v1/transfers/exchange

Transferência de PlataformaPostBeta

Move fundos entre uma wallet e uma conta de plataforma de negociação pertencente ao cliente autenticado. O parâmetro direction define qual o lado debitado: from_wallet financia a conta da plataforma, to_wallet financia a wallet. Quando a wallet e a conta da plataforma têm moedas diferentes, envie também wallet_currency com um exchange_rate cotado e o respetivo rate_token./wallet/v1/transfers/platforms

Autenticação

Todos os endpoints requerem o cabeçalho Deriv-App-ID e um cabeçalho Authorization: Bearer YOUR_OAUTH_TOKEN. O token deve ter o âmbito payment; caso contrário, a API devolve 403 Forbidden.

Âmbitos OAuth2

Endpoint	Permissão
`GET /wallet/v1/wallets`	`payment`
`GET /wallet/v1/transactions/{wallet_type}`	`payment`
`GET /wallet/v1/exchange-rate`	`payment`
`POST /wallet/v1/transfers/validate`	`payment`
`POST /wallet/v1/transfers`	`payment`
`POST /wallet/v1/transfers/exchange`	`payment`
`POST /wallet/v1/transfers/platforms`	`payment`

1curl -X GET "https://api.derivws.com/wallet/v1/wallets?conversion_currency=USD" \
2  -H "Deriv-App-ID: YOUR_APP_ID" \
3  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Códigos de Estado da Resposta

A API usa códigos de estado HTTP padrão para indicar sucesso ou falha:

2xx Sucesso

200 OK — Pedido bem-sucedido

Erros 4xx/5xx

400 Bad Request — Parâmetros inválidos

401 Unauthorized — Autenticação inválida ou em falta

403 Forbidden — O token não possui o âmbito payment

404 Not Found — Wallet não encontrada

429 Too Many Requests — Limite de pedidos excedido

500 Internal Server Error — Erro do lado do servidor

503 Service Unavailable — Pedido rejeitado pelo disjuntor do gateway

504 Gateway Timeout — Timeout de serviço upstream

Formato de Resposta de Erro

Todas as respostas de erro seguem um envelope consistente com um array errors. Cada entrada contém um status numérico, um code legível por máquina e uma message legível por humanos:

1{
2  "errors": [
3    {
4      "status": 400,
5      "code": "BadRequest",
6      "message": "conversion_currency must be a 3-letter ISO currency code"
7    }
8  ]
9}

Os códigos de erro incluem: BadRequest, ValidationError, CurrencyNotAllowed, DailyLimitError, DuplicateRequestID, Unauthorized, NotFound, InternalServerError

Estado de Levantamento Lista de Wallets

Alguma outra questão? Entrar em contacto